External ID Types

External ID Types register external systems that you want to map to Addepar entities and groups. Each type represents one source system (a CRM, custodian, order management platform). Once a type is registered, its key becomes part of the attribute name pattern (external_id_{type_key}) used to assign identifiers on individual entities.

You create types once per external system. The actual mapping of entities to external records happens through the Entities or Groups API by setting the external_id_{type_key} attribute. See External Identifiers for the full workflow.

Overview

📘

Access requirements

All operations require "API Access: Create, edit, and delete" and "Manage firm settings: Full Access."

Resource attributes

The resource id is the same as external_type_key.

Key constraints

• external_type_key is immutable. Once created, the key cannot be renamed. It becomes embedded in entity attribute names across the firm. Choose a short, stable identifier (e.g., salesforce, schwab, custodian_feed).
• Types in use cannot be deleted. If any entity or group has a value set for external_id_{type_key}, the DELETE request returns 400 Bad Request. Remove all assignments first.
• Keys must be unique within a firm. Attempting to create a duplicate returns 409 Conflict.

Get all external ID types

GET /v1/external_id_types

curl -X GET "https://{firm}.addepar.com/api/v1/external_id_types" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Accept: application/vnd.api+json"

{
  "data": [
    {
      "id": "salesforce",
      "type": "external_id_types",
      "attributes": {
        "external_type_key": "salesforce",
        "display_name": "Salesforce"
      },
      "links": { "self": "/v1/external_id_types/salesforce" }
    },
    {
      "id": "schwab",
      "type": "external_id_types",
      "attributes": {
        "external_type_key": "schwab",
        "display_name": "Charles Schwab"
      },
      "links": { "self": "/v1/external_id_types/schwab" }
    }
  ],
  "included": [],
  "links": { "next": null }
}

Response codes:

• 200 OK -- Success
• 403 Forbidden -- Insufficient permissions

Get an external ID type

GET /v1/external_id_types/:id

The :id is the external_type_key.

curl -X GET "https://{firm}.addepar.com/api/v1/external_id_types/salesforce" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Accept: application/vnd.api+json"

Response codes:

• 200 OK -- Success
• 403 Forbidden -- Insufficient permissions
• 404 Not Found -- Type key does not exist

Create an external ID type

Register a new external system. After creation, you can assign identifiers to entities using external_id_{type_key} as an attribute.

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": "dynamics",
        "display_name": "Microsoft Dynamics"
      }
    }
  }'

{
  "data": {
    "id": "dynamics",
    "type": "external_id_types",
    "attributes": {
      "external_type_key": "dynamics",
      "display_name": "Microsoft Dynamics"
    },
    "links": { "self": "/v1/external_id_types/dynamics" }
  },
  "included": []
}

Response codes:

• 201 Created -- Success
• 403 Forbidden -- Insufficient permissions
• 409 Conflict -- external_type_key already exists

Update an external ID type

Only display_name can be changed. The external_type_key is permanent.

PATCH /v1/external_id_types/:id

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

Response codes:

• 200 OK -- Success
• 403 Forbidden -- Insufficient permissions
• 404 Not Found -- Type does not exist

Delete an external ID type

Removes the type registration from the firm. Fails if any entity or group currently has a value assigned for this type.

DELETE /v1/external_id_types/:id

curl -X DELETE "https://{firm}.addepar.com/api/v1/external_id_types/dynamics" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Accept: application/vnd.api+json"

204 No Content

Response codes:

• 204 No Content -- Deleted
• 400 Bad Request -- Type is in use (assigned to entities or groups). Remove all assignments first.
• 403 Forbidden -- Insufficient permissions
• 404 Not Found -- Type does not exist

📘

Related

• External Identifiers -- Concept guide and integration workflow
• Entities -- Assign external IDs via PATCH on entity attributes
• Groups -- Assign external IDs to groups
• Portfolio Query -- Scope queries using external IDs