> For the complete user guide index, see [llms.txt](https://portraitresearch.com/documentation/llms.txt).

# Portrait Partner API

[Canonical page](https://portraitresearch.com/documentation/integrations/partner-api/)

## Applicability

- **Task:** Use the partner data API with its own audience, scopes, access requirements, and error contract.
- **Access:** Provisioned Partner API environment; enabled partner organization; partner-audience user or machine token and required scopes
- **Audience:** Portrait users and support teams
- **Surfaces:** api
- **Availability:** Account-dependent; see requirements and limits
- **Content type:** reference
- **Last reviewed:** 2026-09-24

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

1. 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.
2. 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.
3. Request the scopes required by the operation: `companies:read`, `documents:read`, or `gen_content:read`.
4. 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.