Annual Report Filing Workflow

Annual reports are required compliance filings to maintain good standing with state authorities. This workflow shows how to automate filings across multiple jurisdictions using the SingleFile API.

How It Works

Your App                    SingleFile API               State Authority
   |                             |                             |
   |--- GET /schemas ----------->|                             |
   |<-- jurisdiction rules ------|                             |
   |                             |                             |
   |--- POST /order/create ----->|                             |
   |<-- order_id + status -------|                             |
   |                             |---- annual report --------->|
   |                             |<--- filing confirmation ----|
   |<-- webhook: completed ------|                             |

Jurisdiction Requirements at a Glance

	Delaware	California	Washington
Complexity	Minimal	Detailed	Moderate
Officers	Basic (name, title)	Full (name, title, director status)	Basic
Financials	No	Yes (shares, FEIN)	Revenue breakdowns
Fiscal year	No	Yes (begin/end dates)	No
Processing	1-2 business days	1-2 business days	1-2 business days

File annual reports before the due date to avoid penalties and maintain good standing. Set up webhooks or polling to track filing status.

Prerequisites

Valid API access token
Existing entity ID (entity must already be formed)
Jurisdiction information
Current entity information (officers, addresses, business activities)

Step 1: Retrieve Annual Report Schema

Get the specific schema requirements for your entity type and jurisdiction:

#!/bin/bash
BASE_URL="https://api.demo.singlefile.io"
ACCESS_TOKEN="your_bearer_token_here"
ENTITY_TYPE="llc"
JURISDICTION="delaware"

curl -X GET "${BASE_URL}/external-api/v1/schemas?entity_type=${ENTITY_TYPE}&filing_type=annual_report&jurisdiction=${JURISDICTION}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

import requests

def get_annual_report_schema(entity_type, jurisdiction, access_token):
    """Retrieve annual report schema for specific entity type and jurisdiction"""
    
    params = {
        "entity_type": entity_type,
        "filing_type": "annual_report",
        "jurisdiction": jurisdiction
    }
    
    response = requests.get(
        "https://api.demo.singlefile.io/external-api/v1/schemas",
        params=params,
        headers={"Authorization": f"Bearer {access_token}"}
    )
    
    if response.status_code == 200:
        schema = response.json()
        print(f"Retrieved schema for {entity_type} annual report in {jurisdiction}")
        return schema
    else:
        raise Exception(f"Failed to retrieve schema: {response.status_code}")

# Get schema for different jurisdictions
ACCESS_TOKEN = "your_bearer_token_here"

# Delaware LLC Annual Report
delaware_schema = get_annual_report_schema("llc", "delaware", ACCESS_TOKEN)

# California Corporation Annual Report  
california_schema = get_annual_report_schema("corporation", "california", ACCESS_TOKEN)

# Washington LLC Annual Report
washington_schema = get_annual_report_schema("llc", "washington", ACCESS_TOKEN)

const BASE_URL = 'https://api.demo.singlefile.io';

async function getAnnualReportSchema(entityType, jurisdiction, accessToken) {
  const params = new URLSearchParams({
    entity_type: entityType,
    filing_type: 'annual_report',
    jurisdiction: jurisdiction
  });

  const response = await fetch(
    `${BASE_URL}/external-api/v1/schemas?${params}`,
    {
      headers: { 'Authorization': `Bearer ${accessToken}` }
    }
  );

  if (!response.ok) {
    throw new Error(`Failed to retrieve schema: ${response.status}`);
  }
  const schema = await response.json();
  console.log(`Retrieved schema for ${entityType} annual report in ${jurisdiction}`);
  return schema;
}

const accessToken = 'your_bearer_token_here';
const delawareSchema = await getAnnualReportSchema('llc', 'delaware', accessToken);
const californiaSchema = await getAnnualReportSchema('corporation', 'california', accessToken);
const washingtonSchema = await getAnnualReportSchema('llc', 'washington', accessToken);

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
)

func getAnnualReportSchema(entityType, jurisdiction, accessToken string) (map[string]interface{}, error) {
	baseURL := "https://api.demo.singlefile.io"
	reqURL := baseURL + "/external-api/v1/schemas"
	params := url.Values{}
	params.Add("entity_type", entityType)
	params.Add("filing_type", "annual_report")
	params.Add("jurisdiction", jurisdiction)

	req, err := http.NewRequest("GET", reqURL+"?"+params.Encode(), nil)
	if err != nil {
		return nil, err
	}
	req.Header.Set("Authorization", "Bearer "+accessToken)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	if resp.StatusCode != 200 {
		return nil, fmt.Errorf("failed to retrieve schema: %d", resp.StatusCode)
	}
	var schema map[string]interface{}
	if err := json.NewDecoder(resp.Body).Decode(&schema); err != nil {
		return nil, err
	}
	fmt.Printf("Retrieved schema for %s annual report in %s\n", entityType, jurisdiction)
	return schema, nil
}

func main() {
	accessToken := "your_bearer_token_here"
	delawareSchema, _ := getAnnualReportSchema("llc", "delaware", accessToken)
	californiaSchema, _ := getAnnualReportSchema("corporation", "california", accessToken)
	washingtonSchema, _ := getAnnualReportSchema("llc", "washington", accessToken)
	_ = delawareSchema
	_ = californiaSchema
	_ = washingtonSchema
}

using System.Net.Http;
using System.Text.Json;

var baseUrl = "https://api.demo.singlefile.io";
var accessToken = "your_bearer_token_here";

async Task<JsonDocument> GetAnnualReportSchemaAsync(string entityType, string jurisdiction, string accessToken)
{
    using var client = new HttpClient();
    client.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken}");
    
    var query = $"?entity_type={entityType}&filing_type=annual_report&jurisdiction={jurisdiction}";
    var response = await client.GetAsync($"{baseUrl}/external-api/v1/schemas{query}");
    
    if (!response.IsSuccessStatusCode)
        throw new Exception($"Failed to retrieve schema: {response.StatusCode}");
    
    var json = await response.Content.ReadAsStringAsync();
    Console.WriteLine($"Retrieved schema for {entityType} annual report in {jurisdiction}");
    return JsonDocument.Parse(json);
}

var delawareSchema = await GetAnnualReportSchemaAsync("llc", "delaware", accessToken);
var californiaSchema = await GetAnnualReportSchemaAsync("corporation", "california", accessToken);
var washingtonSchema = await GetAnnualReportSchemaAsync("llc", "washington", accessToken);

Step 2: Create Annual Report Payload

The payload structure varies by jurisdiction. Here are examples for three common states:

Delaware LLC — minimal requirements, basic entity info:

# Delaware LLC - payload construction (use with jq or echo for JSON)
ENTITY_ID="entity_123"
ORG_ID="org_456"

# Construct payload as JSON - typically you'd build this in your app and POST it
echo '{
  "client_matter_number": "AR-2024-001",
  "entity_id": "'"$ENTITY_ID"'",
  "filing_type": "Annual Report",
  "jurisdiction": "Delaware",
  "tax_year": 2024,
  "headquarters_address": {
    "street_address": "123 Main Street",
    "city": "Wilmington",
    "state": "DE",
    "postal_code": "19801",
    "country": "US"
  },
  "mailing_address": {
    "street_address": "123 Main Street",
    "city": "Wilmington",
    "state": "DE",
    "postal_code": "19801",
    "country": "US"
  },
  "officers": [{"first_name": "John", "last_name": "Doe", "officer_title": "Manager"}],
  "nature_of_business": "Technology consulting services",
  "telephone_number": "302-555-0123",
  "email": "[email protected]"
}'

def create_delaware_annual_report_payload(entity_id, organization_id):
    """Create annual report payload for Delaware LLC"""
    
    return {
        "client_matter_number": "AR-2024-001",
        "entity_id": entity_id,
        "filing_type": "Annual Report",
        "jurisdiction": "Delaware",
        "tax_year": 2024,
        "headquarters_address": {
            "street_address": "123 Main Street",
            "city": "Wilmington",
            "state": "DE",
            "postal_code": "19801",
            "country": "US"
        },
        "mailing_address": {
            "street_address": "123 Main Street", 
            "city": "Wilmington",
            "state": "DE",
            "postal_code": "19801",
            "country": "US"
        },
        "officers": [
            {
                "first_name": "John",
                "last_name": "Doe",
                "officer_title": "Manager"
            }
        ],
        "nature_of_business": "Technology consulting services",
        "telephone_number": "302-555-0123",
        "email": "[email protected]"
    }

function createDelawareAnnualReportPayload(entityId, organizationId) {
  return {
    client_matter_number: 'AR-2024-001',
    entity_id: entityId,
    filing_type: 'Annual Report',
    jurisdiction: 'Delaware',
    tax_year: 2024,
    headquarters_address: {
      street_address: '123 Main Street',
      city: 'Wilmington',
      state: 'DE',
      postal_code: '19801',
      country: 'US'
    },
    mailing_address: {
      street_address: '123 Main Street',
      city: 'Wilmington',
      state: 'DE',
      postal_code: '19801',
      country: 'US'
    },
    officers: [
      { first_name: 'John', last_name: 'Doe', officer_title: 'Manager' }
    ],
    nature_of_business: 'Technology consulting services',
    telephone_number: '302-555-0123',
    email: '[email protected]'
  };
}

func createDelawareAnnualReportPayload(entityID, organizationID string) map[string]interface{} {
	return map[string]interface{}{
		"client_matter_number": "AR-2024-001",
		"entity_id":            entityID,
		"filing_type":          "Annual Report",
		"jurisdiction":         "Delaware",
		"tax_year":             2024,
		"headquarters_address": map[string]string{
			"street_address": "123 Main Street",
			"city":           "Wilmington",
			"state":          "DE",
			"postal_code":    "19801",
			"country":        "US",
		},
		"mailing_address": map[string]string{
			"street_address": "123 Main Street",
			"city":           "Wilmington",
			"state":          "DE",
			"postal_code":    "19801",
			"country":        "US",
		},
		"officers": []map[string]string{
			{"first_name": "John", "last_name": "Doe", "officer_title": "Manager"},
		},
		"nature_of_business": "Technology consulting services",
		"telephone_number":  "302-555-0123",
		"email":             "[email protected]",
	}
}

static object CreateDelawareAnnualReportPayload(string entityId, string organizationId)
{
    return new
    {
        client_matter_number = "AR-2024-001",
        entity_id = entityId,
        filing_type = "Annual Report",
        jurisdiction = "Delaware",
        tax_year = 2024,
        headquarters_address = new
        {
            street_address = "123 Main Street",
            city = "Wilmington",
            state = "DE",
            postal_code = "19801",
            country = "US"
        },
        mailing_address = new
        {
            street_address = "123 Main Street",
            city = "Wilmington",
            state = "DE",
            postal_code = "19801",
            country = "US"
        },
        officers = new[] { new { first_name = "John", last_name = "Doe", officer_title = "Manager" } },
        nature_of_business = "Technology consulting services",
        telephone_number = "302-555-0123",
        email = "[email protected]"
    };
}

California Corporation — detailed financials, officer info, share details:

# California Corporation - payload construction
ENTITY_ID="entity_789"
echo '{
  "client_matter_number": "AR-2024-002",
  "entity_id": "'"$ENTITY_ID"'",
  "filing_type": "Annual Report",
  "jurisdiction": "California",
  "tax_year": 2024,
  "fiscal_year_begin_date": "2024-01-01",
  "fiscal_year_end": "December 31",
  "accounting_period_start": "2024-01-01",
  "accounting_period_end": "2024-12-31",
  "headquarters_address": {"street_address": "456 Tech Ave", "city": "San Francisco", "state": "CA", "postal_code": "94102", "country": "US"},
  "home_jurisdiction": "Delaware",
  "officers": [
    {"first_name": "Jane", "last_name": "Smith", "officer_title": "President", "is_director": true, "address": {"street_address": "789 Executive Blvd", "city": "Palo Alto", "state": "CA", "postal_code": "94301", "country": "US"}},
    {"first_name": "Bob", "last_name": "Johnson", "officer_title": "Secretary", "is_director": true}
  ],
  "shares": {"common_authorized": 10000000, "common_issued": 1000000},
  "nature_of_business": "Software development",
  "number_of_employees": 25,
  "total_assets": 5000000,
  "gross_receipts": 3500000,
  "fein": "12-3456789",
  "compliance_questions": [{"question": "Does any officer or director have an outstanding final judgment issued by the Division of Labor Standards Enforcement?", "answer": "No"}],
  "authorizing_person": "Jane Smith",
  "authorizing_person_title": "President"
}'

def create_california_annual_report_payload(entity_id, organization_id):
    """Create annual report payload for California Corporation"""
    
    return {
        "client_matter_number": "AR-2024-002",
        "entity_id": entity_id,
        "filing_type": "Annual Report",
        "jurisdiction": "California",
        "tax_year": 2024,
        "fiscal_year_begin_date": "2024-01-01",
        "fiscal_year_end": "December 31",
        "accounting_period_start": "2024-01-01",
        "accounting_period_end": "2024-12-31",
        "headquarters_address": {
            "street_address": "456 Tech Ave",
            "city": "San Francisco",
            "state": "CA",
            "postal_code": "94102",
            "country": "US"
        },
        "home_jurisdiction": "Delaware",
        "officers": [
            {
                "first_name": "Jane",
                "last_name": "Smith",
                "officer_title": "President",
                "is_director": True,
                "address": {
                    "street_address": "789 Executive Blvd",
                    "city": "Palo Alto",
                    "state": "CA",
                    "postal_code": "94301",
                    "country": "US"
                }
            },
            {
                "first_name": "Bob",
                "last_name": "Johnson",
                "officer_title": "Secretary",
                "is_director": True
            }
        ],
        "shares": {
            "common_authorized": 10000000,
            "common_issued": 1000000
        },
        "nature_of_business": "Software development",
        "number_of_employees": 25,
        "total_assets": 5000000,
        "gross_receipts": 3500000,
        "fein": "12-3456789",
        "compliance_questions": [
            {
                "question": "Does any officer or director have an outstanding final judgment issued by the Division of Labor Standards Enforcement?",
                "answer": "No"
            }
        ],
        "authorizing_person": "Jane Smith",
        "authorizing_person_title": "President"
    }

function createCaliforniaAnnualReportPayload(entityId, organizationId) {
  return {
    client_matter_number: 'AR-2024-002',
    entity_id: entityId,
    filing_type: 'Annual Report',
    jurisdiction: 'California',
    tax_year: 2024,
    fiscal_year_begin_date: '2024-01-01',
    fiscal_year_end: 'December 31',
    accounting_period_start: '2024-01-01',
    accounting_period_end: '2024-12-31',
    headquarters_address: {
      street_address: '456 Tech Ave',
      city: 'San Francisco',
      state: 'CA',
      postal_code: '94102',
      country: 'US'
    },
    home_jurisdiction: 'Delaware',
    officers: [
      {
        first_name: 'Jane',
        last_name: 'Smith',
        officer_title: 'President',
        is_director: true,
        address: {
          street_address: '789 Executive Blvd',
          city: 'Palo Alto',
          state: 'CA',
          postal_code: '94301',
          country: 'US'
        }
      },
      { first_name: 'Bob', last_name: 'Johnson', officer_title: 'Secretary', is_director: true }
    ],
    shares: { common_authorized: 10000000, common_issued: 1000000 },
    nature_of_business: 'Software development',
    number_of_employees: 25,
    total_assets: 5000000,
    gross_receipts: 3500000,
    fein: '12-3456789',
    compliance_questions: [
      {
        question: 'Does any officer or director have an outstanding final judgment issued by the Division of Labor Standards Enforcement?',
        answer: 'No'
      }
    ],
    authorizing_person: 'Jane Smith',
    authorizing_person_title: 'President'
  };
}

func createCaliforniaAnnualReportPayload(entityID, organizationID string) map[string]interface{} {
	return map[string]interface{}{
		"client_matter_number":     "AR-2024-002",
		"entity_id":               entityID,
		"filing_type":             "Annual Report",
		"jurisdiction":            "California",
		"tax_year":                2024,
		"fiscal_year_begin_date":  "2024-01-01",
		"fiscal_year_end":         "December 31",
		"accounting_period_start": "2024-01-01",
		"accounting_period_end":   "2024-12-31",
		"headquarters_address": map[string]string{
			"street_address": "456 Tech Ave",
			"city":           "San Francisco",
			"state":          "CA",
			"postal_code":    "94102",
			"country":        "US",
		},
		"home_jurisdiction": "Delaware",
		"officers": []map[string]interface{}{
			{
				"first_name":    "Jane",
				"last_name":     "Smith",
				"officer_title": "President",
				"is_director":   true,
				"address": map[string]string{
					"street_address": "789 Executive Blvd",
					"city":           "Palo Alto",
					"state":          "CA",
					"postal_code":    "94301",
					"country":        "US",
				},
			},
			{"first_name": "Bob", "last_name": "Johnson", "officer_title": "Secretary", "is_director": true},
		},
		"shares":              map[string]int{"common_authorized": 10000000, "common_issued": 1000000},
		"nature_of_business":   "Software development",
		"number_of_employees": 25,
		"total_assets":        5000000,
		"gross_receipts":      3500000,
		"fein":                "12-3456789",
		"compliance_questions": []map[string]string{
			{"question": "Does any officer or director have an outstanding final judgment issued by the Division of Labor Standards Enforcement?", "answer": "No"},
		},
		"authorizing_person":      "Jane Smith",
		"authorizing_person_title": "President",
	}
}

static object CreateCaliforniaAnnualReportPayload(string entityId, string organizationId)
{
    return new
    {
        client_matter_number = "AR-2024-002",
        entity_id = entityId,
        filing_type = "Annual Report",
        jurisdiction = "California",
        tax_year = 2024,
        fiscal_year_begin_date = "2024-01-01",
        fiscal_year_end = "December 31",
        accounting_period_start = "2024-01-01",
        accounting_period_end = "2024-12-31",
        headquarters_address = new { street_address = "456 Tech Ave", city = "San Francisco", state = "CA", postal_code = "94102", country = "US" },
        home_jurisdiction = "Delaware",
        officers = new[]
        {
            new
            {
                first_name = "Jane",
                last_name = "Smith",
                officer_title = "President",
                is_director = true,
                address = new { street_address = "789 Executive Blvd", city = "Palo Alto", state = "CA", postal_code = "94301", country = "US" }
            },
            new { first_name = "Bob", last_name = "Johnson", officer_title = "Secretary", is_director = true }
        },
        shares = new { common_authorized = 10000000, common_issued = 1000000 },
        nature_of_business = "Software development",
        number_of_employees = 25,
        total_assets = 5000000,
        gross_receipts = 3500000,
        fein = "12-3456789",
        compliance_questions = new[] { new { question = "Does any officer or director have an outstanding final judgment issued by the Division of Labor Standards Enforcement?", answer = "No" } },
        authorizing_person = "Jane Smith",
        authorizing_person_title = "President"
    };
}

Washington LLC — revenue breakdowns and business activity details:

# Washington LLC - payload construction
ENTITY_ID="entity_101"
echo '{
  "client_matter_number": "AR-2024-003",
  "entity_id": "'"$ENTITY_ID"'",
  "filing_type": "Annual Report",
  "jurisdiction": "Washington",
  "tax_year": 2024,
  "management_type": "Member-Managed",
  "headquarters_address": {"street_address": "100 Commerce St", "city": "Seattle", "state": "WA", "postal_code": "98101", "country": "US"},
  "mailing_address": {"street_address": "100 Commerce St", "city": "Seattle", "state": "WA", "postal_code": "98101", "country": "US"},
  "home_jurisdiction": "Washington",
  "officers": [
    {"first_name": "Maria", "last_name": "Garcia", "officer_title": "Manager", "ownership_percentage": 60},
    {"first_name": "John", "last_name": "Lee", "officer_title": "Member", "ownership_percentage": 40}
  ],
  "nature_of_business": "Real estate investment",
  "fein": "98-7654321",
  "state_filing_number": "123456789",
  "revenue_details": {
    "jurisdiction_gross_receipts": 750000,
    "gross_receipts_everywhere": 1200000,
    "rents": 700000,
    "interest": 50000,
    "capital_gains_losses": 200000,
    "other_income": 250000
  }
}'

def create_washington_annual_report_payload(entity_id, organization_id):
    """Create annual report payload for Washington LLC"""
    
    return {
        "client_matter_number": "AR-2024-003",
        "entity_id": entity_id,
        "filing_type": "Annual Report",
        "jurisdiction": "Washington",
        "tax_year": 2024,
        "management_type": "Member-Managed",
        "headquarters_address": {
            "street_address": "100 Commerce St",
            "city": "Seattle",
            "state": "WA",
            "postal_code": "98101",
            "country": "US"
        },
        "mailing_address": {
            "street_address": "100 Commerce St",
            "city": "Seattle", 
            "state": "WA",
            "postal_code": "98101",
            "country": "US"
        },
        "home_jurisdiction": "Washington",
        "officers": [
            {
                "first_name": "Maria",
                "last_name": "Garcia",
                "officer_title": "Manager",
                "ownership_percentage": 60
            },
            {
                "first_name": "John",
                "last_name": "Lee",
                "officer_title": "Member",
                "ownership_percentage": 40
            }
        ],
        "nature_of_business": "Real estate investment",
        "fein": "98-7654321",
        "state_filing_number": "123456789",
        "revenue_details": {
            "jurisdiction_gross_receipts": 750000,
            "gross_receipts_everywhere": 1200000,
            "rents": 700000,
            "interest": 50000,
            "capital_gains_losses": 200000,
            "other_income": 250000
        }
    }

function createWashingtonAnnualReportPayload(entityId, organizationId) {
  return {
    client_matter_number: 'AR-2024-003',
    entity_id: entityId,
    filing_type: 'Annual Report',
    jurisdiction: 'Washington',
    tax_year: 2024,
    management_type: 'Member-Managed',
    headquarters_address: {
      street_address: '100 Commerce St',
      city: 'Seattle',
      state: 'WA',
      postal_code: '98101',
      country: 'US'
    },
    mailing_address: {
      street_address: '100 Commerce St',
      city: 'Seattle',
      state: 'WA',
      postal_code: '98101',
      country: 'US'
    },
    home_jurisdiction: 'Washington',
    officers: [
      { first_name: 'Maria', last_name: 'Garcia', officer_title: 'Manager', ownership_percentage: 60 },
      { first_name: 'John', last_name: 'Lee', officer_title: 'Member', ownership_percentage: 40 }
    ],
    nature_of_business: 'Real estate investment',
    fein: '98-7654321',
    state_filing_number: '123456789',
    revenue_details: {
      jurisdiction_gross_receipts: 750000,
      gross_receipts_everywhere: 1200000,
      rents: 700000,
      interest: 50000,
      capital_gains_losses: 200000,
      other_income: 250000
    }
  };
}

func createWashingtonAnnualReportPayload(entityID, organizationID string) map[string]interface{} {
	return map[string]interface{}{
		"client_matter_number": "AR-2024-003",
		"entity_id":            entityID,
		"filing_type":          "Annual Report",
		"jurisdiction":         "Washington",
		"tax_year":             2024,
		"management_type":      "Member-Managed",
		"headquarters_address": map[string]string{
			"street_address": "100 Commerce St",
			"city":           "Seattle",
			"state":          "WA",
			"postal_code":    "98101",
			"country":        "US",
		},
		"mailing_address": map[string]string{
			"street_address": "100 Commerce St",
			"city":           "Seattle",
			"state":          "WA",
			"postal_code":    "98101",
			"country":        "US",
		},
		"home_jurisdiction": "Washington",
		"officers": []map[string]interface{}{
			{"first_name": "Maria", "last_name": "Garcia", "officer_title": "Manager", "ownership_percentage": 60},
			{"first_name": "John", "last_name": "Lee", "officer_title": "Member", "ownership_percentage": 40},
		},
		"nature_of_business":  "Real estate investment",
		"fein":                "98-7654321",
		"state_filing_number": "123456789",
		"revenue_details": map[string]int{
			"jurisdiction_gross_receipts": 750000,
			"gross_receipts_everywhere":   1200000,
			"rents":                       700000,
			"interest":                    50000,
			"capital_gains_losses":        200000,
			"other_income":                250000,
		},
	}
}

static object CreateWashingtonAnnualReportPayload(string entityId, string organizationId)
{
    return new
    {
        client_matter_number = "AR-2024-003",
        entity_id = entityId,
        filing_type = "Annual Report",
        jurisdiction = "Washington",
        tax_year = 2024,
        management_type = "Member-Managed",
        headquarters_address = new { street_address = "100 Commerce St", city = "Seattle", state = "WA", postal_code = "98101", country = "US" },
        mailing_address = new { street_address = "100 Commerce St", city = "Seattle", state = "WA", postal_code = "98101", country = "US" },
        home_jurisdiction = "Washington",
        officers = new[]
        {
            new { first_name = "Maria", last_name = "Garcia", officer_title = "Manager", ownership_percentage = 60 },
            new { first_name = "John", last_name = "Lee", officer_title = "Member", ownership_percentage = 40 }
        },
        nature_of_business = "Real estate investment",
        fein = "98-7654321",
        state_filing_number = "123456789",
        revenue_details = new
        {
            jurisdiction_gross_receipts = 750000,
            gross_receipts_everywhere = 1200000,
            rents = 700000,
            interest = 50000,
            capital_gains_losses = 200000,
            other_income = 250000
        }
    };
}

Step 3: Submit Annual Report Order

Submit the filing using the order creation endpoint:

#!/bin/bash
BASE_URL="https://api.demo.singlefile.io"
ACCESS_TOKEN="your_bearer_token_here"
ORGANIZATION_ID="org_456"

# Build payload (simplified - use jq to merge with order fields)
PAYLOAD='{"client_matter_number":"AR-2024-001","entity_id":"entity_123","filing_type":"Annual Report","jurisdiction":"Delaware","tax_year":2024,"comments":"Annual report filing for 2024","variant":"standard"}'

curl -X POST "${BASE_URL}/external-api/v1/order/create" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

def submit_annual_report_order(payload, organization_id, access_token):
    """Submit annual report order with complete payload"""
    
    # Use the complete annual report payload as the order data
    order_data = payload.copy()  # Start with the complete payload
    
    # Add required order fields
    order_data.update({
        "comments": f"Annual report filing for {payload['tax_year']}",
        "variant": "standard"
    })
    
    response = requests.post(
        "https://api.demo.singlefile.io/external-api/v1/order/create",
        json=order_data,
        headers={
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "application/json"
        }
    )
    
    if response.status_code == 201:
        order = response.json()["data"]
        print(f"Annual report order created: {order['order_id']}")
        return order
    else:
        raise Exception(f"Failed to create order: {response.status_code}")

# Submit annual reports for different jurisdictions
delaware_payload = create_delaware_annual_report_payload("entity_123", "org_456")
delaware_order = submit_annual_report_order(delaware_payload, "org_456", ACCESS_TOKEN)

california_payload = create_california_annual_report_payload("entity_789", "org_456")
california_order = submit_annual_report_order(california_payload, "org_456", ACCESS_TOKEN)

washington_payload = create_washington_annual_report_payload("entity_101", "org_456")
washington_order = submit_annual_report_order(washington_payload, "org_456", ACCESS_TOKEN)

async function submitAnnualReportOrder(payload, organizationId, accessToken) {
  const orderData = {
    ...payload,
    comments: `Annual report filing for ${payload.tax_year}`,
    variant: 'standard'
  };

  const response = await fetch('https://api.demo.singlefile.io/external-api/v1/order/create', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(orderData)
  });

  if (response.status !== 201) {
    throw new Error(`Failed to create order: ${response.status}`);
  }
  const result = await response.json();
  const order = result.data;
  console.log(`Annual report order created: ${order.order_id}`);
  return order;
}

const delawarePayload = createDelawareAnnualReportPayload('entity_123', 'org_456');
const delawareOrder = await submitAnnualReportOrder(delawarePayload, 'org_456', accessToken);
const californiaPayload = createCaliforniaAnnualReportPayload('entity_789', 'org_456');
const californiaOrder = await submitAnnualReportOrder(californiaPayload, 'org_456', accessToken);
const washingtonPayload = createWashingtonAnnualReportPayload('entity_101', 'org_456');
const washingtonOrder = await submitAnnualReportOrder(washingtonPayload, 'org_456', accessToken);

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func submitAnnualReportOrder(payload map[string]interface{}, organizationID, accessToken string) (map[string]interface{}, error) {
	orderData := make(map[string]interface{})
	for k, v := range payload {
		orderData[k] = v
	}
	orderData["comments"] = fmt.Sprintf("Annual report filing for %v", payload["tax_year"])
	orderData["variant"] = "standard"

	jsonBytes, _ := json.Marshal(orderData)
	req, err := http.NewRequest("POST", "https://api.demo.singlefile.io/external-api/v1/order/create", bytes.NewReader(jsonBytes))
	if err != nil {
		return nil, err
	}
	req.Header.Set("Authorization", "Bearer "+accessToken)
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	if resp.StatusCode != 201 {
		return nil, fmt.Errorf("failed to create order: %d", resp.StatusCode)
	}
	var result map[string]interface{}
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		return nil, err
	}
	order := result["data"].(map[string]interface{})
	fmt.Printf("Annual report order created: %v\n", order["order_id"])
	return order, nil
}

using System.Net.Http;
using System.Net;
using System.Text;
using System.Text.Json;

async Task<JsonElement> SubmitAnnualReportOrderAsync(JsonElement payload, string organizationId, string accessToken)
{
    var dict = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(payload.GetRawText());
    var taxYear = payload.GetProperty("tax_year").GetInt32();
    dict["comments"] = JsonSerializer.SerializeToElement($"Annual report filing for {taxYear}");
    dict["variant"] = JsonSerializer.SerializeToElement("standard");

    using var client = new HttpClient();
    client.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken}");
    var content = new StringContent(JsonSerializer.Serialize(dict), Encoding.UTF8, "application/json");
    var response = await client.PostAsync("https://api.demo.singlefile.io/external-api/v1/order/create", content);

    if (response.StatusCode != HttpStatusCode.Created)
        throw new Exception($"Failed to create order: {response.StatusCode}");

    var json = await response.Content.ReadAsStringAsync();
    var result = JsonDocument.Parse(json);
    var order = result.RootElement.GetProperty("data");
    Console.WriteLine($"Annual report order created: {order.GetProperty("order_id")}");
    return order;
}

Step 4: Monitor Order Status

Track the progress of your annual report filings:

#!/bin/bash
BASE_URL="https://api.demo.singlefile.io"
ACCESS_TOKEN="your_bearer_token_here"
ORDER_ID="order_abc123"

curl -X GET "${BASE_URL}/external-api/v1/order/${ORDER_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

def check_order_status(order_id, access_token):
    """Check the status of an annual report order"""
    
    response = requests.get(
        f"https://api.demo.singlefile.io/external-api/v1/order/{order_id}",
        headers={"Authorization": f"Bearer {access_token}"}
    )
    
    if response.status_code == 200:
        order = response.json()["data"]
        print(f"Order {order_id} status: {order['status']}")
        return order
    else:
        raise Exception(f"Failed to get order status: {response.status_code}")

# Check status of submitted orders
delaware_status = check_order_status(delaware_order["order_id"], ACCESS_TOKEN)
california_status = check_order_status(california_order["order_id"], ACCESS_TOKEN)
washington_status = check_order_status(washington_order["order_id"], ACCESS_TOKEN)

async function checkOrderStatus(orderId, accessToken) {
  const response = await fetch(
    `https://api.demo.singlefile.io/external-api/v1/order/${orderId}`,
    { headers: { 'Authorization': `Bearer ${accessToken}` } }
  );

  if (!response.ok) {
    throw new Error(`Failed to get order status: ${response.status}`);
  }
  const result = await response.json();
  const order = result.data;
  console.log(`Order ${orderId} status: ${order.status}`);
  return order;
}

const delawareStatus = await checkOrderStatus(delawareOrder.order_id, accessToken);
const californiaStatus = await checkOrderStatus(californiaOrder.order_id, accessToken);
const washingtonStatus = await checkOrderStatus(washingtonOrder.order_id, accessToken);

func checkOrderStatus(orderID, accessToken string) (map[string]interface{}, error) {
	req, err := http.NewRequest("GET", "https://api.demo.singlefile.io/external-api/v1/order/"+orderID, nil)
	if err != nil {
		return nil, err
	}
	req.Header.Set("Authorization", "Bearer "+accessToken)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	if resp.StatusCode != 200 {
		return nil, fmt.Errorf("failed to get order status: %d", resp.StatusCode)
	}
	var result map[string]interface{}
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		return nil, err
	}
	order := result["data"].(map[string]interface{})
	fmt.Printf("Order %s status: %v\n", orderID, order["status"])
	return order, nil
}

async Task<JsonElement> CheckOrderStatusAsync(string orderId, string accessToken)
{
    using var client = new HttpClient();
    client.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken}");
    var response = await client.GetAsync($"https://api.demo.singlefile.io/external-api/v1/order/{orderId}");

    if (!response.IsSuccessStatusCode)
        throw new Exception($"Failed to get order status: {response.StatusCode}");

    var json = await response.Content.ReadAsStringAsync();
    var result = JsonDocument.Parse(json);
    var order = result.RootElement.GetProperty("data");
    Console.WriteLine($"Order {orderId} status: {order.GetProperty("status")}");
    return order;
}

Tip: Instead of polling, set up webhooks to get notified automatically when your filing completes or encounters an issue.

Complete Annual Report Workflow

Here's a reusable implementation that handles schema retrieval, payload construction, and filing across multiple jurisdictions:

#!/bin/bash
BASE_URL="https://api.demo.singlefile.io"
ACCESS_TOKEN="your_bearer_token_here"
ORGANIZATION_ID="your_organization_id"

# File annual reports for multiple entities
for entity in "123:Delaware:llc" "456:California:corporation" "789:Washington:llc"; do
  IFS=':' read -r entity_id jurisdiction entity_type <<< "$entity"
  echo "Filing annual report for entity $entity_id in $jurisdiction..."
  
  # 1. Get schema
  schema=$(curl -s -X GET "${BASE_URL}/external-api/v1/schemas?entity_type=${entity_type}&filing_type=annual_report&jurisdiction=${jurisdiction,,}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}")
  
  # 2. Build and submit payload (simplified - full payload would include all required fields)
  payload="{\"entity_id\":\"${entity_id}\",\"filing_type\":\"Annual Report\",\"jurisdiction\":\"${jurisdiction}\",\"tax_year\":$(date +%Y),\"comments\":\"Annual report filing\",\"variant\":\"standard\"}"
  order=$(curl -s -X POST "${BASE_URL}/external-api/v1/order/create" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d "$payload")
  
  order_id=$(echo "$order" | jq -r '.data.order_id')
  echo "Submitted: $order_id"
done

import requests
from datetime import datetime

class AnnualReportFiler:
    def __init__(self, access_token, organization_id):
        self.access_token = access_token
        self.organization_id = organization_id
        self.base_url = "https://api.demo.singlefile.io/external-api/v1"
    
    def get_schema(self, entity_type, jurisdiction):
        """Get annual report schema"""
        params = {
            "entity_type": entity_type,
            "filing_type": "annual_report",
            "jurisdiction": jurisdiction
        }
        
        response = requests.get(
            f"{self.base_url}/schemas",
            params=params,
            headers={"Authorization": f"Bearer {self.access_token}"}
        )
        
        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"Schema retrieval failed: {response.status_code}")
    
    def create_annual_report_payload(self, entity_id, jurisdiction, entity_type="llc"):
        """Create jurisdiction-specific annual report payload"""
        
        base_payload = {
            "client_matter_number": f"AR-{datetime.now().year}-{entity_id}",
            "entity_id": entity_id,
            "filing_type": "Annual Report",
            "jurisdiction": jurisdiction,
            "tax_year": datetime.now().year,
            "headquarters_address": {
                "street_address": "123 Business Ave",
                "city": "Business City",
                "state": jurisdiction,
                "postal_code": "12345",
                "country": "US"
            },
            "mailing_address": {
                "street_address": "123 Business Ave",
                "city": "Business City", 
                "state": jurisdiction,
                "postal_code": "12345",
                "country": "US"
            },
            "officers": [
                {
                    "first_name": "John",
                    "last_name": "Doe",
                    "officer_title": "Manager" if entity_type == "llc" else "President"
                }
            ],
            "nature_of_business": "General business activities",
            "telephone_number": "555-0123",
            "email": "[email protected]"
        }
        
        # Add jurisdiction-specific fields
        if jurisdiction.lower() == "california":
            base_payload.update({
                "fiscal_year_begin_date": f"{datetime.now().year}-01-01",
                "fiscal_year_end": "December 31",
                "accounting_period_start": f"{datetime.now().year}-01-01",
                "accounting_period_end": f"{datetime.now().year}-12-31",
                "fein": "12-3456789",
                "compliance_questions": [
                    {
                        "question": "Does any officer or director have an outstanding final judgment issued by the Division of Labor Standards Enforcement?",
                        "answer": "No"
                    }
                ]
            })
        elif jurisdiction.lower() == "washington":
            base_payload.update({
                "management_type": "Member-Managed",
                "fein": "98-7654321",
                "state_filing_number": "123456789"
            })
        
        return base_payload
    
    def submit_annual_report(self, entity_id, jurisdiction, entity_type="llc"):
        """Submit annual report for an entity"""
        
        # Get schema to validate requirements
        schema = self.get_schema(entity_type, jurisdiction)
        
        # Create payload
        payload = self.create_annual_report_payload(entity_id, jurisdiction, entity_type)
        
        # Submit order with complete payload
        order_data = payload.copy()  # Start with the complete annual report payload
        
        # Add required order fields
        order_data.update({
            "comments": f"Annual report filing for {payload['tax_year']}",
            "variant": "standard"
        })
        
        response = requests.post(
            f"{self.base_url}/order/create",
            json=order_data,
            headers={
                "Authorization": f"Bearer {self.access_token}",
                "Content-Type": "application/json"
            }
        )
        
        if response.status_code == 201:
            order = response.json()["data"]
            print(f"Annual report submitted for {jurisdiction}: {order['order_id']}")
            return order
        else:
            raise Exception(f"Order submission failed: {response.status_code}")

# Usage example
ACCESS_TOKEN = "your_bearer_token_here"
ORGANIZATION_ID = "your_organization_id"

filer = AnnualReportFiler(ACCESS_TOKEN, ORGANIZATION_ID)

# File annual reports for multiple entities
entities_to_file = [
    {"entity_id": "123", "jurisdiction": "Delaware", "entity_type": "llc"},
    {"entity_id": "456", "jurisdiction": "California", "entity_type": "corporation"},
    {"entity_id": "789", "jurisdiction": "Washington", "entity_type": "llc"}
]

for entity in entities_to_file:
    try:
        order = filer.submit_annual_report(
            entity["entity_id"],
            entity["jurisdiction"], 
            entity["entity_type"]
        )
        print(f"Successfully submitted annual report for entity {entity['entity_id']}")
    except Exception as e:
        print(f"Failed to submit annual report for entity {entity['entity_id']}: {e}")

const BASE_URL = 'https://api.demo.singlefile.io/external-api/v1';

class AnnualReportFiler {
  constructor(accessToken, organizationId) {
    this.accessToken = accessToken;
    this.organizationId = organizationId;
    this.baseUrl = BASE_URL;
  }

  async getSchema(entityType, jurisdiction) {
    const params = new URLSearchParams({
      entity_type: entityType,
      filing_type: 'annual_report',
      jurisdiction: jurisdiction.toLowerCase()
    });
    const response = await fetch(`${this.baseUrl}/schemas?${params}`, {
      headers: { 'Authorization': `Bearer ${this.accessToken}` }
    });
    if (!response.ok) throw new Error(`Schema retrieval failed: ${response.status}`);
    return response.json();
  }

  createAnnualReportPayload(entityId, jurisdiction, entityType = 'llc') {
    const year = new Date().getFullYear();
    const basePayload = {
      client_matter_number: `AR-${year}-${entityId}`,
      entity_id: entityId,
      filing_type: 'Annual Report',
      jurisdiction,
      tax_year: year,
      headquarters_address: { street_address: '123 Business Ave', city: 'Business City', state: jurisdiction, postal_code: '12345', country: 'US' },
      mailing_address: { street_address: '123 Business Ave', city: 'Business City', state: jurisdiction, postal_code: '12345', country: 'US' },
      officers: [{ first_name: 'John', last_name: 'Doe', officer_title: entityType === 'llc' ? 'Manager' : 'President' }],
      nature_of_business: 'General business activities',
      telephone_number: '555-0123',
      email: '[email protected]'
    };
    if (jurisdiction.toLowerCase() === 'california') {
      basePayload.fiscal_year_begin_date = `${year}-01-01`;
      basePayload.fiscal_year_end = 'December 31';
      basePayload.accounting_period_start = `${year}-01-01`;
      basePayload.accounting_period_end = `${year}-12-31`;
      basePayload.fein = '12-3456789';
      basePayload.compliance_questions = [{ question: 'Does any officer or director have an outstanding final judgment issued by the Division of Labor Standards Enforcement?', answer: 'No' }];
    } else if (jurisdiction.toLowerCase() === 'washington') {
      basePayload.management_type = 'Member-Managed';
      basePayload.fein = '98-7654321';
      basePayload.state_filing_number = '123456789';
    }
    return basePayload;
  }

  async submitAnnualReport(entityId, jurisdiction, entityType = 'llc') {
    await this.getSchema(entityType, jurisdiction);
    const payload = this.createAnnualReportPayload(entityId, jurisdiction, entityType);
    const orderData = { ...payload, comments: `Annual report filing for ${payload.tax_year}`, variant: 'standard' };
    const response = await fetch(`${this.baseUrl}/order/create`, {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${this.accessToken}`, 'Content-Type': 'application/json' },
      body: JSON.stringify(orderData)
    });
    if (response.status !== 201) throw new Error(`Order submission failed: ${response.status}`);
    const result = await response.json();
    const order = result.data;
    console.log(`Annual report submitted for ${jurisdiction}: ${order.order_id}`);
    return order;
  }
}

const filer = new AnnualReportFiler('your_bearer_token_here', 'your_organization_id');
const entitiesToFile = [
  { entity_id: '123', jurisdiction: 'Delaware', entity_type: 'llc' },
  { entity_id: '456', jurisdiction: 'California', entity_type: 'corporation' },
  { entity_id: '789', jurisdiction: 'Washington', entity_type: 'llc' }
];

for (const entity of entitiesToFile) {
  try {
    await filer.submitAnnualReport(entity.entity_id, entity.jurisdiction, entity.entity_type);
    console.log(`Successfully submitted annual report for entity ${entity.entity_id}`);
  } catch (e) {
    console.log(`Failed to submit annual report for entity ${entity.entity_id}: ${e}`);
  }
}

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
	"time"
)

type AnnualReportFiler struct {
	AccessToken    string
	OrganizationID string
	BaseURL        string
}

func NewAnnualReportFiler(accessToken, organizationID string) *AnnualReportFiler {
	return &AnnualReportFiler{
		AccessToken:    accessToken,
		OrganizationID: organizationID,
		BaseURL:        "https://api.demo.singlefile.io/external-api/v1",
	}
}

func (f *AnnualReportFiler) GetSchema(entityType, jurisdiction string) (map[string]interface{}, error) {
	params := url.Values{}
	params.Add("entity_type", entityType)
	params.Add("filing_type", "annual_report")
	params.Add("jurisdiction", jurisdiction)
	req, _ := http.NewRequest("GET", f.BaseURL+"/schemas?"+params.Encode(), nil)
	req.Header.Set("Authorization", "Bearer "+f.AccessToken)
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	if resp.StatusCode != 200 {
		return nil, fmt.Errorf("schema retrieval failed: %d", resp.StatusCode)
	}
	var schema map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&schema)
	return schema, nil
}

func (f *AnnualReportFiler) CreateAnnualReportPayload(entityID, jurisdiction, entityType string) map[string]interface{} {
	year := time.Now().Year()
	basePayload := map[string]interface{}{
		"client_matter_number": fmt.Sprintf("AR-%d-%s", year, entityID),
		"entity_id":            entityID,
		"filing_type":          "Annual Report",
		"jurisdiction":         jurisdiction,
		"tax_year":             year,
		"headquarters_address": map[string]string{"street_address": "123 Business Ave", "city": "Business City", "state": jurisdiction, "postal_code": "12345", "country": "US"},
		"mailing_address":     map[string]string{"street_address": "123 Business Ave", "city": "Business City", "state": jurisdiction, "postal_code": "12345", "country": "US"},
		"officers":             []map[string]string{{"first_name": "John", "last_name": "Doe", "officer_title": "Manager"}},
		"nature_of_business":   "General business activities",
		"telephone_number":    "555-0123",
		"email":               "[email protected]",
	}
	if entityType != "llc" {
		basePayload["officers"] = []map[string]string{{"first_name": "John", "last_name": "Doe", "officer_title": "President"}}
	}
	if jurisdiction == "California" || jurisdiction == "california" {
		basePayload["fiscal_year_begin_date"] = fmt.Sprintf("%d-01-01", year)
		basePayload["fiscal_year_end"] = "December 31"
		basePayload["accounting_period_start"] = fmt.Sprintf("%d-01-01", year)
		basePayload["accounting_period_end"] = fmt.Sprintf("%d-12-31", year)
		basePayload["fein"] = "12-3456789"
		basePayload["compliance_questions"] = []map[string]string{{"question": "Does any officer or director have an outstanding final judgment issued by the Division of Labor Standards Enforcement?", "answer": "No"}}
	} else if jurisdiction == "Washington" || jurisdiction == "washington" {
		basePayload["management_type"] = "Member-Managed"
		basePayload["fein"] = "98-7654321"
		basePayload["state_filing_number"] = "123456789"
	}
	return basePayload
}

func (f *AnnualReportFiler) SubmitAnnualReport(entityID, jurisdiction, entityType string) (map[string]interface{}, error) {
	f.GetSchema(entityType, jurisdiction)
	payload := f.CreateAnnualReportPayload(entityID, jurisdiction, entityType)
	payload["comments"] = fmt.Sprintf("Annual report filing for %v", payload["tax_year"])
	payload["variant"] = "standard"
	jsonBytes, _ := json.Marshal(payload)
	req, _ := http.NewRequest("POST", f.BaseURL+"/order/create", bytes.NewReader(jsonBytes))
	req.Header.Set("Authorization", "Bearer "+f.AccessToken)
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	if resp.StatusCode != 201 {
		return nil, fmt.Errorf("order submission failed: %d", resp.StatusCode)
	}
	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	order := result["data"].(map[string]interface{})
	fmt.Printf("Annual report submitted for %s: %v\n", jurisdiction, order["order_id"])
	return order, nil
}

func main() {
	filer := NewAnnualReportFiler("your_bearer_token_here", "your_organization_id")
	entities := []struct{ entityID, jurisdiction, entityType string }{
		{"123", "Delaware", "llc"},
		{"456", "California", "corporation"},
		{"789", "Washington", "llc"},
	}
	for _, e := range entities {
		if _, err := filer.SubmitAnnualReport(e.entityID, e.jurisdiction, e.entityType); err != nil {
			fmt.Printf("Failed to submit for entity %s: %v\n", e.entityID, err)
		} else {
			fmt.Printf("Successfully submitted annual report for entity %s\n", e.entityID)
		}
	}
}

using System.Net.Http;
using System.Text;
using System.Text.Json;

var baseUrl = "https://api.demo.singlefile.io/external-api/v1";

class AnnualReportFiler
{
    private readonly string _accessToken;
    private readonly string _organizationId;
    private readonly string _baseUrl;

    public AnnualReportFiler(string accessToken, string organizationId)
    {
        _accessToken = accessToken;
        _organizationId = organizationId;
        _baseUrl = baseUrl;
    }

    public async Task<JsonDocument> GetSchemaAsync(string entityType, string jurisdiction)
    {
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", $"Bearer {_accessToken}");
        var query = $"?entity_type={entityType}&filing_type=annual_report&jurisdiction={jurisdiction.ToLower()}";
        var response = await client.GetAsync($"{_baseUrl}/schemas{query}");
        if (!response.IsSuccessStatusCode) throw new Exception($"Schema retrieval failed: {response.StatusCode}");
        return JsonDocument.Parse(await response.Content.ReadAsStringAsync());
    }

    public object CreateAnnualReportPayload(string entityId, string jurisdiction, string entityType = "llc")
    {
        var year = DateTime.Now.Year;
        var basePayload = new Dictionary<string, object>
        {
            ["client_matter_number"] = $"AR-{year}-{entityId}",
            ["entity_id"] = entityId,
            ["filing_type"] = "Annual Report",
            ["jurisdiction"] = jurisdiction,
            ["tax_year"] = year,
            ["headquarters_address"] = new Dictionary<string, string> { ["street_address"] = "123 Business Ave", ["city"] = "Business City", ["state"] = jurisdiction, ["postal_code"] = "12345", ["country"] = "US" },
            ["mailing_address"] = new Dictionary<string, string> { ["street_address"] = "123 Business Ave", ["city"] = "Business City", ["state"] = jurisdiction, ["postal_code"] = "12345", ["country"] = "US" },
            ["officers"] = new[] { new Dictionary<string, string> { ["first_name"] = "John", ["last_name"] = "Doe", ["officer_title"] = entityType == "llc" ? "Manager" : "President" } },
            ["nature_of_business"] = "General business activities",
            ["telephone_number"] = "555-0123",
            ["email"] = "[email protected]"
        };
        if (jurisdiction.Equals("California", StringComparison.OrdinalIgnoreCase))
        {
            basePayload["fiscal_year_begin_date"] = $"{year}-01-01";
            basePayload["fiscal_year_end"] = "December 31";
            basePayload["accounting_period_start"] = $"{year}-01-01";
            basePayload["accounting_period_end"] = $"{year}-12-31";
            basePayload["fein"] = "12-3456789";
            basePayload["compliance_questions"] = new[] { new Dictionary<string, string> { ["question"] = "Does any officer or director have an outstanding final judgment issued by the Division of Labor Standards Enforcement?", ["answer"] = "No" } };
        }
        else if (jurisdiction.Equals("Washington", StringComparison.OrdinalIgnoreCase))
        {
            basePayload["management_type"] = "Member-Managed";
            basePayload["fein"] = "98-7654321";
            basePayload["state_filing_number"] = "123456789";
        }
        return basePayload;
    }

    public async Task<JsonElement> SubmitAnnualReportAsync(string entityId, string jurisdiction, string entityType = "llc")
    {
        await GetSchemaAsync(entityType, jurisdiction);
        var payload = CreateAnnualReportPayload(entityId, jurisdiction, entityType);
        var payloadDict = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(JsonSerializer.Serialize(payload));
        payloadDict["comments"] = JsonSerializer.SerializeToElement($"Annual report filing for {DateTime.Now.Year}");
        payloadDict["variant"] = JsonSerializer.SerializeToElement("standard");
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", $"Bearer {_accessToken}");
        var content = new StringContent(JsonSerializer.Serialize(payloadDict), Encoding.UTF8, "application/json");
        var response = await client.PostAsync($"{_baseUrl}/order/create", content);
        if (response.StatusCode != System.Net.HttpStatusCode.Created) throw new Exception($"Order submission failed: {response.StatusCode}");
        var result = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
        var order = result.RootElement.GetProperty("data");
        Console.WriteLine($"Annual report submitted for {jurisdiction}: {order.GetProperty("order_id")}");
        return order;
    }
}

var filer = new AnnualReportFiler("your_bearer_token_here", "your_organization_id");
var entitiesToFile = new[]
{
    new { entity_id = "123", jurisdiction = "Delaware", entity_type = "llc" },
    new { entity_id = "456", jurisdiction = "California", entity_type = "corporation" },
    new { entity_id = "789", jurisdiction = "Washington", entity_type = "llc" }
};

foreach (var entity in entitiesToFile)
{
    try
    {
        await filer.SubmitAnnualReportAsync(entity.entity_id, entity.jurisdiction, entity.entity_type);
        Console.WriteLine($"Successfully submitted annual report for entity {entity.entity_id}");
    }
    catch (Exception e)
    {
        Console.WriteLine($"Failed to submit annual report for entity {entity.entity_id}: {e}");
    }
}

Key Considerations

Field Category	Required By	Examples
Entity identification	All jurisdictions	`entity_id`, `jurisdiction`, `tax_year`
Addresses	All jurisdictions	`headquarters_address`, `mailing_address`
Officers / managers	All jurisdictions	Name, title, director status (CA)
Nature of business	All jurisdictions	Business activity description
Contact info	All jurisdictions	Phone, email
Financial details	California, Washington	Shares, FEIN, revenue breakdowns
Fiscal period	California	`fiscal_year_begin_date`, `fiscal_year_end`

Best Practices:

Validate early — use the schema endpoint to check required fields before building payloads

File on time — set calendar reminders or automated triggers before due dates

Batch filings — use the Complete Workflow pattern above to file across multiple jurisdictions in one run

Track everything — monitor order status via webhooks or polling for compliance records

What's Next?

Business Entity Formation — Form new entities before filing annual reports
EIN Filing Workflow — Obtain federal tax IDs for your entities
Document Management — Search and download filed annual report documents
Webhook Setup — Get real-time notifications on filing status changes