The Partner API is Portrait's separately provisioned data interface under /partner-api. It works only after the Portrait account team enables your partner organization in the target environment. Use its partner OpenAPI contract for company information, source documents, and supported generated content. It is separate from the Portrait app's internal API, Portrait MCP, and the Easel API; those tokens and contracts are not interchangeable.
Before you integrate
- Confirm with the Portrait account team that the target environment and your partner organization are enabled. Ask for the provisioned base URL, audience, authentication details, and current Partner API OpenAPI document.
- Obtain an access token for the partner API audience using the provisioned user or machine-to-machine flow. A valid Portrait app token does not establish partner access.
- Request the scopes required by the operation:
companies:read,documents:read, orgen_content:read. - Make a read request from the supplied contract and check both the response and any error body. Use the partner schema for parameters and returned fields; do not copy internal app endpoints.
User tokens are attributed to the analyst's partner organization. Machine tokens must belong to a client mapped to an enabled partner organization. User impersonation is not supported. Feature provisioning, organization entitlement, token audience, and scopes are separate checks.
Verify the contract
Confirm that the specification identifies the /partner-api surface and the operation you need. The current contract covers company discovery and details, filings and transcripts, and available company-generated content. Access does not imply every company or document is covered or licensed. Follow the supplied schema's pagination and identifiers rather than assuming the Easel or MCP contract applies.
Operations
The paths below are relative to the provisioned /partner-api base. Parameters, result models, and pagination come from the supplied OpenAPI document.
| Method and path | Purpose | Required scope |
|---|---|---|
GET /v1/ping |
Verify authenticated connectivity | Partner token |
GET /v1/companies/search |
Resolve company identities | companies:read |
POST /v1/documents/search |
Search supported filings | documents:read |
POST /v1/documents/by-companies |
Retrieve filings for specified companies | documents:read |
GET /v1/documents/{document_id} |
Read filing metadata | documents:read |
GET /v1/documents/{document_id}/content |
Read available filing content | documents:read |
GET /v1/company-primers/{ticker} |
Read an available company primer | gen_content:read |
GET /v1/case-studies/{ticker} |
List company case studies | gen_content:read |
GET /v1/case-studies/{ticker}/{year}/{quarter} |
Read a quarterly case study | gen_content:read |
GET /v1/company-graph/{ticker} |
Read recorded company relationships | gen_content:read |
GET /v1/company-graph/edges/sources |
Read evidence for relationship edges | gen_content:read |
These are endpoint templates, not links to a configured environment. Resolve an unambiguous company before requesting its content. Availability of a company record does not establish availability of all generated content or document text.
Errors and recovery
| Status or code | Meaning and recovery |
|---|---|
401 invalid_token or access_token_expired |
Supply or refresh the correct partner-audience access token. Do not paste it into support chat. |
403 partner_access_denied |
The identity or organization lacks active partner access. Ask the account team to check provisioning. |
403 insufficient_scope |
Request the operation's required scope; the authentication header identifies missing scopes. Signing in again with unchanged scopes will not grant it. |
403 impersonation_not_supported |
Remove the impersonation request and use the authorized partner principal. |
| 404 across the Partner API surface | Confirm the provisioned environment and base URL. An environment without Partner API configuration does not expose the surface. A route-specific missing item is a separate issue. |
422 validation_error |
Correct the parameters described in the response's errors. |
422 unresolved_tickers |
Review every unresolved ticker and candidate composite ticker. Choose the intended listing explicitly; ambiguous listings are not selected automatically. ETFs, indices, and funds can be outside the company catalog. |
429 rate_limited |
Wait the Retry-After interval. Limits are shared across the partner organization, including its users and machine clients; switching accounts does not create an independent budget. |
500 internal_error |
Retain the redacted response and request time, and contact support if the failure persists. Do not repeatedly retry without bounds. |
Contact support
Provide the target environment, operation, timestamp, status, and public error code. Include a redacted parameter example when needed to explain ticker resolution. Never include access tokens, client secrets, or private returned data. The in-app support assistant cannot provision access or execute API requests for you.