Customers

These are end-user customers, individuals or businesses that your product onboards onto the platform. They're scoped to your org. They are NOT the same thing as your org's own KYB onboarding, which lives under Orgs → KYB profile.

The surface is polymorphic. A Customer carries a type discriminator ("individual" or "business"). Profile data lives in a nested profile sub-object whose shape is picked by type (a KycProfile for individuals, a KybProfile for businesses). Every endpoint accepts either kind on the same URL and returns the right shape based on type.

All endpoints under /customers require auth, either an Api-Key: <key> (org-scoped, recommended) or Authorization: Bearer <access-token> (dashboard session). Customers are filtered to the org bound to the credential. Curl snippets assume $SEISMIC_ORCHESTRATION_URL and $SEISMIC_ORCHESTRATION_API_KEY, see Auth for the full model.

Endpoints

Lifecycle

• POST /customers, create a customer (individual or business). Returns the new id and an auto-minted kyc_link.
• GET /customers, list and filter customers, with cursor paging.
• GET /customers/:id, read a customer envelope: type, profile, and the inline kyc_link. GET /customers/:id/kyc/profile is an alias.
• PUT /customers/:id/kyc/profile, upsert the profile body. Accepts partial drafts. Returns the same envelope.
• POST /customers/:id/kyc/submit, submit for verification (KYC for individuals, KYB for businesses).
• POST /customers/:id/kyc/sync-approvals, submit for any verification checks added since the customer was onboarded.
• GET /customers/:id/kyc/state, read the current verification state.
• GET /customers/:id/kyc/rfis, read the open requests for information on the verification.
• POST /customers/:id/kyc/resync, force a fresh sync of the cached verification verdict.

Hosted KYC link

Every customer carries a kyc_link inline on every read. Auto-minted at create-time. No separate endpoint needed to fetch it.

• POST /customers/:id/kyc-link/rotate, overwrite the token in place after a suspected leak. Returns the new { token, url }.

Documents

• POST /customers/:id/kyc/documents, upload a supporting document.
• GET /customers/:id/kyc/documents, list documents.
• DELETE /customers/:id/kyc/documents/:doc_id, detach a document.

Orders

An order is the record created when a quote is accepted (see POST /quotes/:id/accept).

• GET /customers/orders, list and filter orders across every customer.
• GET /customers/:id/orders, list one customer's orders.
• GET /customers/orders/:id, read a single order by id.
• POST /customers/orders/:id/cancel, cancel an order still awaiting_funds or pending.
• POST /customers/orders/:id/documents, submit the supporting document a held payment is waiting for.

Per-customer accounts

Live under Accounts: the create + read endpoints for a customer's fiat / crypto accounts all hang off /customers/:id/accounts/* but are documented in the Accounts section to keep this page focused on KYC/KYB.

Types

Customer

A polymorphic envelope returned by retrieve and update. The envelope carries the identity discriminator (type), the saved profile, and the inline kyc_link. Verification status (KYC for individuals, KYB for businesses) is not denormalized onto this record. Read it from GET /customers/:id/kyc/state instead.

POST /customers returns the smaller { type, id, kyc_link } shape (no profile echoed back). Pass id back on every subsequent call.

Profile fields can be partially populated pre-submit. The wizard saves drafts via PUT /customers/:id/kyc/profile. Submit-time validation runs on POST /customers/:id/kyc/submit.

HostedKycLink

The partner-issued, Seismic-hosted KYC/KYB link. Every customer carries one inline on every read. No separate fetch endpoint exists. Partners share the url with their end-customer, who lands on a standalone wizard at /kyc-link/<kind>/<token> and fills in their own verification. The URL itself is the credential, so anyone with it can read and write that one customer's profile, upload documents, and submit. It cannot read other customers, mint other links, or act on the org.

No expiry, no revocation: if a token leaks, rotate it. Each rotation overwrites the token in place and 404s the previous URL.

Individual customer (type: "individual"): url carries the ind segment:

{
  "token": "klink_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w",
  "url": "https://orchestration.seismic.systems/kyc-link/ind/klink_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w"
}

Business customer (type: "business"): same field name kyc_link, but url carries the biz segment:

{
  "token": "klink_b9c8d7e6f5g4h3i2j1k0l9m8n7o6p5q4r3s2t1u0v9w8x",
  "url": "https://orchestration.seismic.systems/kyc-link/biz/klink_b9c8d7e6f5g4h3i2j1k0l9m8n7o6p5q4r3s2t1u0v9w8x"
}

Sandbox-issued links carry the same shape with the seismictest.net origin, e.g. https://orchestration.seismictest.net/kyc-link/ind/klink_….

The bi segment is reserved for business-individual links (B2B2C end-users of a business customer). The wizard for that flow isn't part of the public API surface yet.

Address

Shared shape used in profile.addresses.residential, profile.addresses.mailing (KYC), profile.addresses.registered, profile.addresses.physical (KYB, via OperatingAddress), and per-UBO profile.associated_persons[].address (KYB).

No PO boxes.

Both conditional rules resolve per country. GET /customers/address-requirements answers them for one country ahead of submit, so a form can hide the fields that country's address format doesn't have.

OperatingAddress

profile.addresses.physical (KYB) only. Every Address field, sent inline.

operating_is_remote

Set profile.addresses.operating_is_remote (KYB) when the business has no office and the address it operates from is the residential address of a control person. Seismic adds a statement to that effect to the supplemental information document it sends to compliance review.

physical stays optional. Send it when the residence the business operates from is not the registered address already on the profile:

{
  "addresses": {
    "operating_is_remote": true,
    "physical": {
      "line1": "88 Cedar Ave",
      "city": "Austin",
      "state": "TX",
      "postal_code": "78701",
      "country": "US"
    }
  }
}

The flag and the operating address have to agree, in both directions. Only beneficial owners count — an associated_persons entry without the beneficial_owner role has no residence the business can be operating out of:

• With the flag set and a physical address sent, that address must match the address of one of the profile's beneficial owners — otherwise submission fails with an other violation on addresses.physical.
• When physical does match a beneficial owner's address, the flag must be set — otherwise submission fails with a not_in_allowed_set violation on addresses.operating_is_remote.

Addresses are compared as premises, not as strings: casing, extra whitespace and postal-code separators don't matter, but Ave and Avenue are different addresses.

The declaration also covers the company's proof of address: the beneficial owner whose residential address matches the operating address proves it with their own proof_of_address document, so no company-level one is required at submit. A company proof_of_address uploaded anyway is deduplicated by file name against that person's document, or kept as other with the description "Alternate proof of address for the company".

Addresses sent without either flag read as operating_is_remote: false, so existing payloads are unaffected.

Country codes

Every country-valued field takes an ISO-3166-1 alpha-2 code: two uppercase letters, such as SG, US, GB. Country names are rejected — "Singapore" fails validation, "SG" is what the field wants. The same rule covers nationality, citizenship, country_of_birth, country_of_residence, phone_country_code, gov_id_country, country_of_registration, regulated_authority_country, and the jurisdiction arrays.

City-states repeat the name across the address. city keeps the human-readable name ("Singapore"), country still takes the code ("SG"), and state is omitted because Singapore's address format has no state or region. Not every city-state drops state: Hong Kong's format includes an area, so HK addresses require one.

Correct:

{
  "line1": "1 Raffles Place",
  "city": "Singapore",
  "postal_code": "048616",
  "country": "SG"
}

Rejected:

{
  "line1": "1 Raffles Place",
  "city": "Singapore",
  "state": "Singapore",
  "postal_code": "048616",
  "country": "Singapore"
}

Phone numbers

Every profile phone (contact.phone, and phone on each associated person) is checked at submit in two steps:

• Shape. E.164: +, the country calling code, then the national number, with no spaces or punctuation — 8–15 digits after the +.
• Digits for the calling code. The number must fall in a real number range for its calling code, checked against published per-country numbering plans. Lengths vary by country and by line type, so there is no single digit count to aim for.

Two mistakes account for most rejections:

• The national trunk prefix is kept. A leading 0 dialled inside the country is not part of the E.164 number: UK 07911 123456 is +447911123456, not +4407911123456. Italy is the exception — its leading 0 stays (+390212345678).
• The calling code is typed twice. Singapore 8753 1018 is +6587531018, not +656587531018.

A number that fails either step is rejected with invalid_format on its field, and the message names the calling code. A calling code with no published numbering plan is checked for shape only.

TransliteratedAddress

Latin-1 form of an address whose canonical fields contain non-Latin-1 characters (Cyrillic, CJK, Arabic, etc.). Sanctions / PEP screening runs against Latin-only databases, so the romanized form is required alongside the original. All-or-nothing: when the canonical address triggers the requirement, every required canonical field needs a Latin counterpart. country is omitted. ISO-3166 codes are always Latin-1.

KycProfile

The unified individual-KYC profile body. Lives under profile on an individual customer envelope. Read it via GET /customers/:id/kyc/profile, write it via PUT /customers/:id/kyc/profile.

identity

Social profile

identity.social_profile_url takes an http/https link to the customer's profile on one of four networks:

• linkedin.com
• facebook.com
• instagram.com
• x.com (twitter.com is accepted for links saved under the old domain)

Subdomains are fine, so https://www.linkedin.com/in/alice and https://m.facebook.com/alice both pass. A link to any other host is rejected at submit with a NotInAllowedSet violation on identity.social_profile_url, and a value that isn't a usable link is rejected as InvalidFormat.

The field is optional. Submissions that omit it succeed exactly as before. A future release will require it for customers whose government ID was issued outside the US, EU or Canada — that change will get its own changelog entry and advance notice before it takes effect.

addresses

contact

employment

EmploymentStatus

One of:

• employee
• self_employed
• retired
• unemployed
• homemaker
• student
• other: set employment_description alongside.

risk

AML questionnaire. Self-attested.

SourceOfFunds

Where the customer's funds come from. One of:

• salary
• savings
• business_revenue
• company_capital
• investment_returns
• inheritance
• trust
• gift
• grant
• sale_of_assets
• real_estate
• loan
• private_capital
• marital
• winnings
• other

On a business (KYB) profile, primary_source_of_funds_description is required whatever value is chosen. On an individual (KYC) profile, only other requires it.

AccountPurpose

Why the customer is opening this account. Every value is accepted for individual and business customers alike, but we recommend picking from the per-kind list below — a purpose outside its list can reach review as free text instead of a category, which clears slower. The hosted verification wizard offers exactly these, in this order; mirror it when you build your own form so a customer sees the same choices in the same order.

Recommended for a consumer (individual customer):

1. salary_collections: receive my salary.
2. personal_use: pay for personal expenses.
3. remittances: make payments to friends or family abroad.
4. purchase_goods_and_services: pay for goods and services.
5. savings: store savings.
6. investment: make investments.
7. freelance_collections: receive my freelance payments.
8. charitable_donations: make charitable donations.
9. other: set account_purpose_explanation alongside.

Recommended for a business customer:

1. purchase_goods_and_services: pay for goods and services.
2. receive_payments_for_goods_and_services: receive payments for goods and services.
3. investment: make investments.
4. ecommerce_collections: accept retail e-commerce payments.
5. charitable_donations: make or receive charitable donations.
6. other: set account_purpose_explanation alongside.

Accepted, but not recommended for either kind:

• crypto_investment: reviewed the same as investment. Send investment.
• payroll: paying employees or contractors. Reviewed the same as purchase_goods_and_services. Send that instead.
• business_operations: legacy. Accepted for existing integrations — submits as other with the purpose as account_purpose_explanation.
• treasury_management: legacy. Same handling as business_operations.

volumes

Estimated transaction counts and exact USD figures. Nonnegative. 0 is valid.

jurisdictions

HighRiskActivity

One of:

• adult_entertainment
• gambling
• marijuana
• drugs
• firearms
• crypto_mixing: operating a crypto tumbler / mixer service.
• money_services
• lending_or_banking
• foreign_exchange
• hold_client_funds
• investment_services
• safe_deposit_box
• tobacco
• pharmaceuticals
• third_party_payment_processing
• none_of_the_above: explicit negative. Exclusive — sending it alongside any other value is rejected at submit. Send it on its own to disclose that none apply.

BusinessClassification

One of:

• marketplace: gig platforms, booking platforms, delivery apps, app stores.
• financial_services_provider: fintech companies, e.g. non-custodial neobanks, wallets, card programs, payment processors, remittance apps — including ones that never touch the flow of funds.
• none_of_the_above: explicit negative. Exclusive — sending it alongside any other value is rejected at submit. Send it on its own to disclose that none apply.

marketplace and financial_services_provider each imply acting_as_intermediary. Either one must also upload a flow_of_funds and a Provider Attestation (licensed_vendors_attestation) document at submit, and must answer in_flow_of_funds (true or false) — see documents.

CounterpartyType

Who the customer expects to transact with. One of:

• self_transactions
• merchants_suppliers
• customers
• employees
• contractors
• friends
• family

attestations

Submission-time attestations. Both must be true at submit (some hosted KYC flows collect them on the form instead, when that's the case, leave them as the default false and they'll be set when the customer agrees in-flow).

documents

Government-issued ID metadata + supporting documents. Bytes are uploaded separately via POST /customers/:id/kyc/documents. The profile carries document_id references.

GovernmentIdentification

SupportingDocumentRef

GovIdKind

New submissions accept:

• passport
• drivers_license
• national_id

Existing profile reads can also return legacy values:

• residence_permit
• voters_card
• other

supplemental

Free-form entries for responding when review asks for more information — a text note or a supplemental document, each with a title and description. The section itself is optional at submit; the rules below apply to each entry sent. It is omitted from the response while empty, and profile saves are full-replace: a PUT /customers/:id/kyc/profile that omits supplemental clears the section, so echo the existing entries (with their ids) on every save they should survive.

Example

A fully-populated profile body for an individual customer:

{
  "identity": {
    "first_name": "Alice",
    "middle_name": "Margaret",
    "last_name": "Liddell",
    "date_of_birth": "1985-06-15",
    "nationality": "US",
    "citizenship": "US",
    "gender": "female",
    "country_of_birth": "US",
    "country_of_residence": "US",
    "tax_identification_number": "123-45-6789",
    "social_profile_url": "https://www.linkedin.com/in/alice-liddell"
  },
  "addresses": {
    "residential": {
      "line1": "1 Wall St",
      "city": "New York",
      "state": "NY",
      "postal_code": "10005",
      "country": "US"
    }
  },
  "contact": {
    "email": "alice@example.com",
    "phone": "+12025550100",
    "phone_country_code": "US"
  },
  "employment": {
    "employment_status": "employee",
    "occupation_soc": "15-1252",
    "employer_name": "Acme Inc."
  },
  "risk": {
    "primary_source_of_funds": "salary",
    "source_of_wealth": "savings",
    "account_purpose": "personal_use",
    "acting_as_intermediary": false,
    "pep_status": false
  },
  "volumes": {
    "usd_value_of_fiat": 120000,
    "usd_value_of_crypto": 25000,
    "monthly_deposits": 4,
    "monthly_withdrawals": 2,
    "monthly_crypto_deposits": 1,
    "monthly_crypto_withdrawals": 0,
    "monthly_investment_deposit_usd": 500,
    "monthly_investment_withdrawal_usd": 0,
    "monthly_crypto_investment_deposit_usd": 0,
    "monthly_crypto_investment_withdrawal_usd": 0
  },
  "jurisdictions": {
    "funds_send_receive_jurisdictions": [
      "US",
      "GB"
    ],
    "high_risk_activities": [
      "none_of_the_above"
    ],
    "vendors_and_counterparties": [
      "self_transactions",
      "merchants_suppliers"
    ]
  },
  "attestations": {
    "terms_and_conditions_accepted": true,
    "information_attested": true
  },
  "documents": {
    "government_issued_identification": {
      "kind": "passport",
      "number": "X12345678",
      "country": "US",
      "front_image_document_id": "8e3b…"
    },
    "supporting_documents": [
      {
        "kind": "selfie",
        "document_id": "c07a…"
      },
      {
        "kind": "proof_of_address",
        "document_id": "1f4d…"
      }
    ]
  },
  "supplemental": [
    {
      "id": "0e8b…",
      "kind": "text",
      "title": "Clarification on settlement volumes",
      "description": "Q3 volume increase reflects two new enterprise clients onboarded in July."
    },
    {
      "id": "7f1a…",
      "kind": "document",
      "title": "March bank statement",
      "description": "Statement covering the period referenced in the review.",
      "document_id": "b2c3…"
    }
  ]
}

KybProfile

The unified business-KYB profile body. Lives under profile on a business customer envelope. Read it via GET /customers/:id/kyc/profile, write it via PUT /customers/:id/kyc/profile.

The shape matches the org's own KybProfile one-for-one. Same sub-sections, same enums, same submit-time validation. The difference is who's being verified: the integrator's own KYB lives under /v0/org/kyb/*. This body verifies the integrator's end-customer businesses.

business

EntityType

One of:

• sole_proprietorship
• llc
• s_corporation
• c_corporation
• b_corporation
• non_profit
• partnership
• limited_partnership
• limited_liability_partnership
• trust
• dao
• cooperative
• other

addresses

contact

operations

Compliance / jurisdiction context.

RegulatedStatus

One of:

• regulated
• registered: set the regulated_* fields alongside.
• licensed
• not_required

volumes

Estimated monthly transaction counts plus exact USD figures. Nonnegative. 0 is valid.

counterparties

attestations

Submission-time attestations. Both must be true at submit.

associated_persons

Add all beneficial owners (individuals with ≥25% ownership) and directors. Every business must have at least one beneficial owner and at least one director, even if it is the same person.

At submit time:

• At least one entry is required.
• At least one entry must include "beneficial_owner" in its roles array.
• Every entry whose ownership_percent is 25 or more must include "beneficial_owner" in its roles array. Below 25 the role is optional.
• At least one entry must include "control_person" or "officer" in its roles array.
• At least one entry must include "authorized_signer" in its roles array.
• From November 14, 2026, every entry must also include at least one of "control_person", "officer", "director", or "authorized_signer". An entry whose only role is "beneficial_owner" is rejected with a violation on associated_persons[i].roles.
• Every entry must carry a full government-ID block (gov_id_kind, gov_id_number, gov_id_country, and gov_id_front_image_document_id), plus a selfie_document_id and a proof_of_address_document_id.
• Sum of ownership_percent across all entries must be ≤ 100. Sums under 100 are accepted. The residual represents holders below the disclosure threshold (per FinCEN's CDD rule, only ≥25% holders need be individually identified). Values accept up to two decimal places, so fractional stakes (e.g. three owners at "33.33" each) sum to 100 instead of being forced to whole numbers that overshoot.

Linking a person to an individual customer

The same human is often both an individual customer of yours and a beneficial owner on a business customer's KYB profile. Set customer_id on the associated person to the individual customer's id and Seismic treats them as one person, reusing that customer's verification instead of putting them through it a second time.

Seismic accepts the link only when the two records identify the same person beyond doubt. The individual customer must belong to your organization and must match the submitted person on at least one of:

• tax_id (compared with formatting removed, so 123-45-6789 and 123456789 agree),
• email (case-insensitive), or
• first_name and last_name (case-insensitive) and date_of_birth.

Anything short of that — an unknown id, a customer in another organization, or details that don't line up — rejects the whole profile save with a 422 kyb_profile_incomplete violation on associated_persons[i].customer_id.

Profile writes are full replacements, so a PUT that omits customer_id on a person removes any link that person had. Send the field on every save you want the link to survive.

The field applies to business customers only. Sending it on your organization's own KYB profile is rejected.

To find the customer to link rather than tracking the pairing yourself, ask GET /customers/:id/kyc/associated-persons/:person_id/link-suggestions — it returns the individual customers that already match this person under the rules above.

SourceOfWealth

One of:

• salary
• dividends
• property_rental
• investment
• inheritance
• gambling
• donation

EconomicActivity

Multi-select. An entry can carry any combination.

• employed
• self_employed
• student
• gambler
• pensioner
• unemployed

AssociatedPersonRole

Multi-select. An entry can carry any combination.

• beneficial_owner: ≥25% direct or indirect ownership.
• control_person: exercises significant control / management.
• officer: named officer (CEO, CFO, etc.). Sets title.
• director: board member.
• authorized_signer: empowered to sign on behalf of the entity.

supplemental

Free-form entries for responding when review asks for more information — a text note or a supplemental document, each with a title and description. The section itself is optional at submit; the rules below apply to each entry sent. It is omitted from the response while empty, and profile saves are full-replace: a PUT /customers/:id/kyc/profile that omits supplemental clears the section, so echo the existing entries (with their ids) on every save they should survive.

documents

Business-level supporting documents (incorporation certificate, bank statement, ownership chart, etc.). Bytes are uploaded separately via POST /customers/:id/kyc/documents. Read this list to see what's been uploaded against the customer (the per-UBO government IDs are tracked under each associated_persons[].gov_id_*_image_document_id).

Each entry is a KybDocumentRef.

Required: business_formation, ownership_information, proof_of_nature_of_business, plus either a bank_statement or a ubo_bank_statement together with a proof_of_address. A business that sets operations.registered_msb must upload a flow_of_funds. A business whose operations.business_classifications includes marketplace or financial_services_provider must upload a flow_of_funds and a Provider Attestation (licensed_vendors_attestation). A business that sets business.pre_revenue must upload a ubo_source_of_funds. An org's own KYB additionally requires a Provider Attestation and a flow_of_funds whatever its answers say. See Required at submit for the full rules and the missing[] paths each gap reports.

Example

A fully-populated profile body for a business customer:

{
  "business": {
    "legal_name": "Acme Inc.",
    "trade_name": "Acme",
    "description": "Acme Inc. operates a marketplace connecting suppliers and merchants worldwide.",
    "entity_type": "c_corporation",
    "is_dao": false,
    "industry": "425120",
    "registration_number": "1234567",
    "tax_id": "82-1234567",
    "country_of_registration": "US",
    "state_of_incorporation": "DE",
    "formation_date": "2020-04-12",
    "website": "https://acme.example"
  },
  "addresses": {
    "registered": {
      "line1": "1 Wall St",
      "city": "New York",
      "state": "NY",
      "postal_code": "10005",
      "country": "US"
    }
  },
  "contact": {
    "email": "ops@acme.com",
    "phone": "+12025550100",
    "phone_country_code": "US"
  },
  "operations": {
    "business_jurisdictions": [
      "US"
    ],
    "funds_movement_jurisdictions": [
      "US",
      "GB"
    ],
    "primary_source_of_funds": "company_capital",
    "regulated_status": "not_required",
    "account_purpose": "purchase_goods_and_services",
    "registered_msb": false,
    "licensed_vendors": false,
    "operates_in_prohibited_countries": false,
    "high_risk_activities": [
      "none_of_the_above"
    ],
    "has_complex_ownership": false,
    "business_classifications": [
      "none_of_the_above"
    ],
    "acting_as_intermediary": false
  },
  "volumes": {
    "monthly_deposits": 35,
    "monthly_withdrawals": 30,
    "monthly_investment_deposit_usd": 0,
    "monthly_investment_withdrawal_usd": 0,
    "monthly_crypto_investment_deposit_usd": 0,
    "monthly_crypto_investment_withdrawal_usd": 0,
    "usd_value_of_fiat": 5000000,
    "usd_value_of_crypto": 0,
    "expected_monthly_payments_usd": 250000,
    "estimated_annual_revenue_usd": 5000000
  },
  "counterparties": {
    "counterparties": [
      "customers",
      "merchants_suppliers"
    ]
  },
  "attestations": {
    "terms_and_conditions_accepted": true,
    "information_attested": true
  },
  "associated_persons": [
    {
      "id": "5e3a…",
      "first_name": "Alice",
      "last_name": "Liddell",
      "date_of_birth": "1985-06-15",
      "email": "alice@acme.com",
      "phone": "+12025550100",
      "phone_country_code": "US",
      "address": {
        "line1": "1 Wall St",
        "city": "New York",
        "state": "NY",
        "postal_code": "10005",
        "country": "US"
      },
      "tax_id": "123-45-6789",
      "nationality": "US",
      "citizenship": "US",
      "gender": "female",
      "country_of_birth": "US",
      "source_of_wealth": "salary",
      "previous_economic_activity": [
        "employed"
      ],
      "ownership_percent": "100",
      "roles": [
        "beneficial_owner",
        "officer",
        "director",
        "authorized_signer"
      ],
      "title": "CEO",
      "relationship_established_at": "2020-04-12",
      "gov_id_kind": "passport",
      "gov_id_number": "X12345678",
      "gov_id_country": "US",
      "gov_id_front_image_document_id": "8e3b…",
      "selfie_document_id": "c07a…",
      "proof_of_address_document_id": "b921…"
    }
  ],
  "supplemental": [
    {
      "id": "0e8b…",
      "kind": "text",
      "title": "Clarification on settlement volumes",
      "description": "Q3 volume increase reflects two new enterprise clients onboarded in July."
    },
    {
      "id": "7f1a…",
      "kind": "document",
      "title": "March bank statement",
      "description": "Statement covering the period referenced in the review.",
      "document_id": "b2c3…"
    }
  ],
  "documents": [
    {
      "document_id": "1f4d…",
      "kind": "articles_of_association",
      "filename": "acme-articles.pdf",
      "content_type": "application/pdf",
      "size_bytes": 184213,
      "uploaded_at": "2026-05-10T20:14:21.045Z"
    }
  ]
}

KyStatus

The unified verification lifecycle, used for both kyc_status (on individuals) and kyb_status (on businesses).

CustomerState

Polymorphic state envelope returned by POST /customers/:id/kyc/submit, POST /customers/:id/kyc/sync-approvals, GET /customers/:id/kyc/state, and POST /customers/:id/kyc/resync. The type discriminator picks the field names inside state (kyc_status / kyc_link for individuals, kyb_status / kyb_link for businesses). The rest of the field set is identical.

state (KYC variant, when type === "individual"):

state (KYB variant, when type === "business"): same fields with kyb_status and kyb_link substituted for the kyc_* names.

Account

A working account. Embedded on the response to the four POST /customers/:id/accounts/{kind}/{origin} endpoints (under account, when one exists yet), returned by GET /accounts/:id, the per-kind GETs (fiat, crypto), and GET /accounts. Also embedded in quote responses when a leg resolves from an attached account.

Account normally represents a usable account. The creating lifecycle (still-pending, partial failures, retries) lives on the separate AccountCreationRequest resource, but so callers can watch one stream instead of two, a virtual account that Seismic hasn't finished provisioning (or couldn't provision) also appears here with status: "pending" / "failed".

kind + shape together determine the layout of details: kind=fiat, shape=us → details is a UsBankFiatAccount. kind=crypto, shape=evm → details is a CryptoAccount. Narrow on kind first, then narrow details structurally.

Closed accounts

A closed account has been retired. It can no longer receive deposits, and it carries no details — the field is absent, not blanked, so there is nothing to mistake for a live identifier. Any account number, IBAN or wallet address you previously showed for it must not be used again.

Closing is not deleting. A closed account keeps its place in GET /accounts and GET /accounts/:id, and its payments, deposits and orders stay queryable, so history stays intact. DELETE /accounts/:id is the destructive counterpart: a deleted account disappears from both endpoints.

Closure is announced on the account.updated webhook. The embedded account in that event reads status: "closed" and carries no details, so the event itself is enough to retire the account in your own systems — no follow-up read required.

To list them, filter on status=closed.

FiatShape

Discriminator for the fiat-side details block. Lists only the shapes wired end-to-end today, more land as Seismic adds settlement support.

"us" | "uk" | "iban" | "swift" | "cn_cnaps" | "hk_fps" | "sg_fast" | "in_ifsc" | "mx_clabe" | "ar_cbu" | "ph_bank" | "thb_bank" | "idr_bank" | "ca_eft" | "pk_iban" | "ng_bank" | "br_pix" | "br_bank" | "au_bsb" | "co_bank"

CryptoShape

Discriminator for the crypto-side details block. Lists only the shapes wired end-to-end today, more land as Seismic adds settlement support.

"evm" | "sol"

External crypto accounts accept evm and sol; the shape is inferred from the selected rail when omitted.

FiatAccount

Account.details (and AccountCreationRequest.details) when kind === "fiat". One of the concrete wired shapes, keyed by Account.shape. Narrow structurally on the present field set, "routing_number" in account.details selects the US-bank variant.

The request-side counterparts live on POST /customers/:id/accounts/fiat/external. Fiat external create accepts the bank-identifier fields under details and the legal owner under top-level account_holder. Response details includes account_holder_name derived from that holder block where applicable.

On a virtual account, account_holder_name starts as the account holder's name and is replaced by the beneficiary name the issuing bank prints once the account is active. Quote the active account's account_holder_name in payment instructions.

shape: "us"

shape: "uk"

shape: "swift"

shape: "iban"

shape: "cn_cnaps"

shape: "hk_fps"

shape: "sg_fast"

shape: "in_ifsc"

shape: "mx_clabe"

shape: "ar_cbu"

shape: "ph_bank"

shape: "thb_bank"

shape: "idr_bank"

shape: "ca_eft"

shape: "pk_iban"

shape: "ng_bank"

shape: "br_pix"

shape: "br_bank"

shape: "au_bsb"

shape: "co_bank"

CryptoAccount

Account.details (and AccountCreationRequest.details) when kind === "crypto". Same shape on the request side (POST /customers/:id/accounts/crypto/external) for origin: "external".

AccountCreationRequest

Returned by the four POST /customers/:id/accounts/{kind}/{origin} endpoints (under request), GET /customers/:id/accounts/requests/:id, and the idempotency-key lookup. Carries the lifecycle of the creation, distinct from the Account it produces, which only exists once Seismic has finished registering / provisioning.

details mirrors the materialized Account.details. For origin: "external", details is always set from the caller-supplied bank / wallet info. Fiat responses add account_holder_name from the top-level account_holder block where applicable. For origin: "virtual", details is absent until provisioning completes. Callers can still derive the eventual layout from kind + shape.