External IDs

External Identifiers link Addepar entities and groups to records in other systems. Every CRM sync, custodian feed, order management integration, and reporting pipeline that maps Addepar data to external records depends on external IDs. They let you query portfolio data using your system's identifiers instead of looking up Addepar IDs first, eliminating the most common source of integration fragility: hardcoded ID mappings.

An external identifier has two parts: a type (representing the external system, like "salesforce" or "custodian_feed") and a value (the record ID in that system, like "MDM123" or "ACCT-00472"). The type is registered once via the External ID Types API, then applied as an attribute on any entity or group.

How external identifiers work

External IDs are stored as attributes on entities. The attribute key follows the pattern external_id_{type_key}, where type_key is the identifier you chose when creating the external ID type.

Once an entity has an external ID assigned, you can use it anywhere the API accepts a portfolio scope:

• Portfolio Query accepts external_ids as an alternative to portfolio_id
• Transactions Query accepts external_ids for portfolio scoping
• Any integration that needs to look up an Addepar entity can search by external ID instead of maintaining a separate ID mapping table

This means your CRM, custodian, or order management system never needs to know Addepar's internal entity IDs. The external ID is the bridge.

Setup workflow

1. Create an external ID type

Register a type for each external system. You only do this once per system.

POST /v1/external_id_types

curl -X POST "https://{firm}.addepar.com/api/v1/external_id_types" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "external_id_types",
      "attributes": {
        "external_type_key": "salesforce",
        "display_name": "Salesforce"
      }
    }
  }'

The external_type_key becomes part of the attribute name (external_id_salesforce) and cannot be changed after creation. Choose a short, stable identifier.

See External ID Types for the full CRUD reference on types.

2. Assign external IDs to entities

Apply the external ID as an attribute on any entity using PATCH. The attribute key is external_id_{type_key} and the value is the record's identifier in the external system.

PATCH /v1/entities/:id

curl -X PATCH "https://{firm}.addepar.com/api/v1/entities/217" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "id": "217",
      "type": "entities",
      "attributes": {
        "external_id_salesforce": "MDM123"
      }
    }
  }'

You can assign external IDs in bulk by including them in a bulk PATCH on the Entities API.

3. Query using external IDs

Pass external_ids instead of (or alongside) portfolio_id in any portfolio-scoped query:

POST /v1/portfolio/query

curl -X POST "https://{firm}.addepar.com/api/v1/portfolio/query" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "portfolio_query",
      "attributes": {
        "columns": [
          { "key": "value", "arguments": { "time_point": "current", "currency": "USD" } },
          { "key": "node_id" }
        ],
        "groupings": [
          { "key": "asset_class" },
          { "key": "ownership" }
        ],
        "filters": [],
        "portfolio_type": "entity",
        "portfolio_id": [],
        "external_ids": [
          {
            "external_type_key": "salesforce",
            "external_id": "MDM123"
          }
        ],
        "start_date": "2021-06-29",
        "end_date": "2021-07-29"
      }
    }
  }'

The external_ids array can contain multiple entries (same type or different types) to scope the query across several entities.

Common integration patterns

CRM sync (Salesforce, Dynamics, HubSpot): Create one external ID type per CRM. When onboarding a client entity, assign the CRM contact/account ID. Subsequent queries and reconciliation can reference the CRM ID directly without maintaining a lookup table.

Custodian feeds: Custodians assign their own account numbers. Create an external ID type per custodian (e.g., schwab, fidelity, pershing). When processing the daily feed, use the custodian account number to find the Addepar entity immediately.

Multi-system reconciliation: An entity can have multiple external IDs from different types simultaneously. A single account entity might carry external_id_salesforce, external_id_schwab, and external_id_ordermgmt all at once.

Deduplication on onboarding: Before creating an entity, check if one already exists with the same external ID: GET /v1/entities?fields[entities]=external_id_salesforce and filter client-side. This prevents duplicate entity creation from retried imports.

Viewing in the application

External IDs appear in the Addepar UI:

1. Open a portfolio with external IDs assigned.
2. Navigate to the Analysis tab.
3. Click the pencil icon (upper right of the data table).
4. Add an "External ID" column and select the type.

📘

Related

• External ID Types -- Create and manage external system registrations
• Entities -- Assign external IDs via entity PATCH
• Portfolio Query -- Use external IDs to scope analytics queries
• Transactions Query -- Use external IDs to scope transaction retrieval
• Addepar Attributes -- External IDs follow the attribute model