Investors

Partner-managed investor onboarding is the default in the Zest Public API: you run KYC on your side and POST the resulting investor records to Zest. Zest persists each row as a Person and returns a stable zestPersonId for use in subscription flows.

Bulk import endpoint

POST /v1/investors

The endpoint accepts an array of individual-investor records. Institutional/entity investors are not supported on this endpoint in v1 — those will surface in a follow-up endpoint.

Request body

{
  "investors": [
    {
      "partnerInvestorId": "acme-inv-7341",

      "firstName": "Alice",
      "lastName": "Liddell",
      "dateOfBirth": "1985-04-12",
      "isUSBased": true,
      "citizenship": "US",

      "email": "alice@example.com",
      "phoneCountryCode": "1",
      "phoneNumber": "4155550100",

      "residentialAddress": {
        "street1": "123 Maple Street",
        "street2": "Unit 2",
        "city": "Maple Town",
        "state": "CA",
        "zipCode": "94033",
        "countryCode": "US"
      },
      "mailingAddress": {
        "street1": "123 Maple Street",
        "street2": "Unit 2",
        "aptSuiteNo": "Apt 4B",
        "city": "Maple Town",
        "state": "CA",
        "zipCode": "94033",
        "country": "US"
      },

      "taxId": "123-45-6789",
      "hasBackupWithholding": false,
      "exemptPayeeCode": null,

      "isSubscriptionAdvisorOrERA": false,
      "qualifiedStatus": "QUALIFIED_PURCHASER",

      "passportNumber": "P12345678"
    }
  ]
}

On success, the response returns zestPersonId per row. Use it on subsequent POST /v1/spvs/{slug}/subscriptions, POST .../forms, and POST .../fundings calls to identify the investor. If you ever see 404 not_found on a subscription create for a zestPersonId returned by POST /v1/investors, surface the errorId to Zest support — never retry the investor create as a workaround.

KYC documents

POST /v1/investors/{zestPersonId}/kyc-documents

Zest needs a KYC evidence file for every investor before it accepts a subscription for them. Upload that evidence with this endpoint. It works only for investors you created through POST /v1/investors. The request is multipart/form-data.

curl -X POST "https://sandbox-api.zestequity.com/v1/investors/psn_abc123/kyc-documents" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "idDocument=@passport.pdf;type=application/pdf" \
  -F "otherDocuments=@source-of-funds.pdf;type=application/pdf" \
  -F "otherDocuments=@bank-letter.png;type=image/png" \
  -F "approvalComments=Reviewed by compliance on 2026-10-16."

Fields

Send any combination of these fields. At least one is required.

Field	Kind	Stored `type`	Required for subscriptions
`idDocument`	file	`id-document`	yes
`idVerificationReport`	file	`id-verification-report`	yes
`proofOfAddress`	file	`proof-of-address`	yes
`kycForm`	file	`kyc-form`	yes
`screeningResults`	file	`screening-result`	yes
`riskAssessment`	file	`risk-assessment`	yes
`approvalDocument`	file	`compliance-approval`	yes, unless `approvalComments` is sent
`approvalComments`	text	`compliance-approval`	yes, unless `approvalDocument` is sent
`otherDocuments`	file, repeatable, max 10	`other`	no

Rules

A request may send any subset of the fields. You can upload everything at once or in several requests.
Each request is stored separately. A later upload never overwrites earlier evidence, so to correct a document, upload it again.
Each file is at most 10 MB and must be PDF, JPEG, PNG or WEBP.
approvalComments is at most 5000 characters (after trimming); longer text returns 400 invalid_request.
approvalComments or approvalDocument satisfies the compliance-approval requirement. Sending both is fine.
Only documents uploaded through this endpoint by your application count toward the requirement.
An unknown zestPersonId, an investor created by another partner, and an investor you did not create all return the same 404 not_found.

Response

A successful request returns 201 Created. missingRequiredTypes lists what is still outstanding. Subscriptions for the investor are refused until it is empty.

{
  "createdAt": "2026-10-16T09:30:00Z",
  "documents": [
    { "type": "id-document", "name": "ID document" },
    { "type": "other", "name": "source-of-funds.pdf" },
    { "type": "other", "name": "bank-letter.png" }
  ],
  "missingRequiredTypes": [
    "id-verification-report",
    "proof-of-address",
    "kyc-form",
    "screening-result",
    "risk-assessment"
  ]
}

Status	Code	Cause
`400`	`invalid_request`	No fields sent, more than 10 `otherDocuments`, or `approvalComments` longer than 5000 characters.
`401`	`invalid_token`	Token missing, malformed, or expired.
`403`	`forbidden`	Application not provisioned for the partner API.
`404`	`not_found`	Investor not found for your application.
`413`	`payload_too_large`	A file is larger than 10 MB.
`415`	`unsupported_media_type`	A file is not PDF, JPEG, PNG or WEBP.

Field reference

Control plane

Field	Required	Type	Notes
`partnerInvestorId`	yes	string	Stable partner-side investor identifier. Used for response correlation, idempotent dedupe, webhook correlation. See Correlation.

Personal

Field	Required	Type	Notes
`firstName`	yes	string
`lastName`	yes	string
`dateOfBirth`	yes	string	ISO date `YYYY-MM-DD`.
`isUSBased`	yes	boolean	Your tax-status determination for the investor. Used downstream for W-9 vs W-8 form selection.
`citizenship`	yes	string	ISO-3166 alpha-2 country code (legal nationality). Validated per row.

Contact

Field	Required	Type	Notes
`email`	yes	string	Must be a valid email.
`phoneCountryCode`	yes	string	Numeric country dialling code without leading `+` (e.g., `"1"` for US, `"971"` for UAE).
`phoneNumber`	yes	string	Subscriber number, no formatting.

`residentialAddress` (nested, required)

Field	Required	Type	Notes
`street1`	yes	string
`street2`	no	string \| null
`city`	yes	string
`state`	yes	string	State / province / region. No central validation — you’re responsible for sending what’s correct for the country.
`zipCode`	yes	string	Postal code.
`countryCode`	yes	string	ISO-3166 alpha-2. Validated per row.

`mailingAddress` (nested, required)

Used for tax + subscription document delivery. Often identical to residentialAddress but separated for jurisdictions where they differ.

Field	Required	Type	Notes
`street1`	yes	string
`street2`	no	string \| null
`aptSuiteNo`	no	string \| null	Mailing-specific apt/suite designator.
`city`	yes	string
`state`	yes	string
`zipCode`	yes	string
`country`	yes	string	ISO-3166 alpha-2. Note the field name is `country` here, not `countryCode` (matches the source spec). Validated per row.

Tax

Field	Required	Type	Notes
`taxId`	yes	string	SSN or foreign tax ID. No format validation — send what the investor’s jurisdiction requires.
`hasBackupWithholding`	yes (nullable)	boolean \| null	Field must be present; `null` is accepted when unknown.
`exemptPayeeCode`	no	string \| null	IRS exempt payee code if applicable.

Compliance

Field	Required	Type	Notes
`isSubscriptionAdvisorOrERA`	yes	boolean	Whether the investor is registered as a Subscription Adviser or Exempt Reporting Adviser. Note the `ERA` acronym is uppercase on the wire.
`qualifiedStatus`	yes (nullable)	enum \| null	See Qualified status below.

Identification

Field	Required	Type	Notes
`passportNumber`	yes (nullable)	string \| null	Field must be present; `null` is accepted when unavailable.

Required-nullable convention

Three fields (hasBackupWithholding, qualifiedStatus, passportNumber) are required-nullable: the key MUST appear in your JSON body, but the value MAY be null. Omitting the key entirely returns 400 validation_error; sending null is valid.

Qualified status

qualifiedStatus accepts one of the following enum values, or null:

QUALIFIED_PURCHASER
QUALIFIED_CLIENT
TRUSTEE_QUALIFIED_PURCHASER
KNOWLEDGEABLE_EMPLOYEE
KNOWLEDGEABLE_EXECUTIVE

Any other string value returns 400 validation_error at the request level.

Partial-success semantics

The endpoint always returns 200 OK with a per-row result envelope. A single bad row never fails the batch (with the exception of request-level validation errors — see Failure cases below).

{
  "results": [
    {
      "partnerInvestorId": "acme-inv-7341",
      "status": "created",
      "zestPersonId": "psn_abc123",
      "error": null
    },
    {
      "partnerInvestorId": "acme-inv-7342",
      "status": "failed",
      "zestPersonId": null,
      "error": {
        "code": "invalid_country_code",
        "field": "citizenship",
        "message": "Unrecognized country code: USA",
        "retryable": false
      }
    },
    {
      "partnerInvestorId": "acme-inv-7343",
      "status": "already_exists",
      "zestPersonId": "psn_def456",
      "error": null
    }
  ]
}

Row status	Meaning	Action
`created`	New person row inserted.	Persist the returned `zestPersonId`. Webhook `investor.created` will fire.
`already_exists`	Replay of a previously-created `partnerInvestorId`.	Use the returned `zestPersonId`; no webhook fires.
`failed`	Row-level validation error.	Inspect `error.code` + `error.retryable`. Fix and resubmit.

Per-row error codes

Code	Triggered when	`retryable`
`invalid_format`	`dateOfBirth` is not ISO `YYYY-MM-DD`.	false
`invalid_country_code`	`citizenship`, `residentialAddress.countryCode`, or `mailingAddress.country` is not a valid ISO-3166 alpha-2 code. `error.field` carries the wire path of the offending field.	false
`institutional_not_supported`	Row carries `investorType: "institutional"` (entity investors are a separate endpoint).	false
`missing_field`	A nested field expected by Zest was absent. `error.field` carries the name.	false
`server_error`	Unexpected exception while persisting the row. `error.message` is a redacted summary.	true

Correlation: `partnerInvestorId`

partnerInvestorId is the stable join key between your system and Zest. It must be:

Unique within your tenant.
Present on every row (no nulls).
Stable across retries.

Zest persists the (client_id, partnerInvestorId) -> zestPersonId mapping. Replaying the same id always returns the existing zestPersonId, never a fresh one. This makes the endpoint safe to retry under any failure mode — duplicates are deduplicated.

Idempotency layers

There are two independent layers of replay protection:

Row-level dedup via partnerInvestorId (always on).
Response caching via Idempotency-Key header (24h TTL, optional).

For long-running bulk imports, layer (1) is sufficient — even if your client crashes mid-batch and you retry from scratch, all created rows return already_exists on the second pass. For interactive single-row creates, add Idempotency-Key so the cached response is served byte-for-byte on retry.

Webhook fan-out

Each created row fires one investor.created webhook with a minimal payload — only the six fields needed for correlation:

{
  "partnerInvestorId": "acme-inv-7341",
  "zestPersonId": "psn_abc123",
  "email": "alice@example.com",
  "firstName": "Alice",
  "lastName": "Liddell",
  "kycManagedBy": "partner"
}

Sensitive fields you sent in the create (such as taxId, passportNumber, addresses) do not appear in the webhook payload — they stay inside Zest. If you need the full investor record later, request a fetch endpoint (currently a deferred follow-up; raise with Zest support). already_exists and failed rows do not fire webhooks — replays are silent on the wire.

Failure cases

Scenario	Behaviour
Missing required field at the request level (e.g., `firstName` absent)	`400 validation_error` for the entire batch; no rows processed.
`qualifiedStatus` not in the enum	`400 validation_error` for the entire batch.
`email` not a valid email	`400 validation_error` for the entire batch.
Invalid ISO country code in any of the three country fields	`200 OK` with per-row `status: "failed"`, `code: "invalid_country_code"`. Other rows in the batch still process.
`partnerInvestorId` repeated within the same batch	First wins; subsequent rows return `already_exists` with the same `zestPersonId`.
Email collision with a different `partnerInvestorId`	Row succeeds and links to the existing Person under the new `partnerInvestorId`. Use stable emails per investor.
Tenant not provisioned for the partner API	`403 forbidden` at the request level.
Token invalid	`401 invalid_token` at the request level.

Getting Started

Concepts

Webhooks

Reference

Bulk import endpoint

Request body

KYC documents

Fields

Rules

Response

Field reference

Control plane

Personal

Contact

`residentialAddress` (nested, required)

`mailingAddress` (nested, required)

Tax

Compliance

Identification

Required-nullable convention

Qualified status

Partial-success semantics

Per-row error codes

Correlation: `partnerInvestorId`

Idempotency layers

Webhook fan-out

Failure cases

​Bulk import endpoint

​Request body

​KYC documents

​Fields

​Rules

​Response

​Field reference

​Control plane

​Personal

​Contact

​residentialAddress (nested, required)

​mailingAddress (nested, required)

​Tax

​Compliance

​Identification

​Required-nullable convention

​Qualified status

​Partial-success semantics

​Per-row error codes

​Correlation: partnerInvestorId

​Idempotency layers

​Webhook fan-out

​Failure cases

Bulk import endpoint

Request body

KYC documents

Fields

Rules

Response

Field reference

Control plane

Personal

Contact

`residentialAddress` (nested, required)

`mailingAddress` (nested, required)

Tax

Compliance

Identification

Required-nullable convention

Qualified status

Partial-success semantics

Per-row error codes

Correlation: `partnerInvestorId`

Idempotency layers

Webhook fan-out

Failure cases