Derivatives Migration

The Derivatives Migration API provides endpoints for migrating legacy derivatives to the new derivative model with underlying assets, or reverting back to legacy format.

🔒 Access requirements

"API Access: Create, edit, and delete" application permission and PORTFOLIO OAuth scope are required.

Migrate derivatives

POST /v1/derivatives/migration migrates legacy derivatives based on filter criteria.

The migration process:

• Identifies derivatives matching the provided criteria
• Creates underlying asset entities for each unique underlying security
• Links the derivatives to their corresponding underlying assets
• Returns a summary of successful migrations, ignored nodes, and any errors

🔑 Authentication

All requests require a base64-encoded API key pair:

Authorization: Basic {base64(key_id:key_secret)}

See Access & Authentication for setup.

Request body

The request accepts one or more filter criteria to identify which derivatives to migrate.

Filter types:

Multiple criteria can be combined. The migration processes all derivatives matching all provided criteria.

curl -X POST "https://{firm}.addepar.com/api/v1/derivatives/migration" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "criteria": [
      {
        "type": "underlying_node",
        "value": 200
      },
      {
        "type": "node_type",
        "value": "STRUCTURED_PRODUCT"
      }
    ]
  }'

HTTP/1.1 200

{
  "node_count": 5,
  "nodes_migrated_count": 3,
  "nodes_migrated": [1001, 1002, 1003],
  "ignore_summaries": [
    {
      "ignore_reason_message": "Derivative already migrated",
      "affected_node_count": 1,
      "affected_node_ids": ["1004"]
    }
  ],
  "error_summaries": [
    {
      "error_message": "Missing required underlying asset information",
      "affected_node_count": 1,
      "affected_node_ids": ["1005"]
    }
  ]
}

Response fields

Response codes:

• 200 OK -- Success
• 400 Bad Request -- Invalid payload (e.g., missing required fields, invalid filter criteria)
• 403 Forbidden -- Not permitted to make the request

Downgrade derivatives

POST /v1/derivatives/migration/downgrade reverts derivatives from the new derivative model back to legacy format.

The downgrade process:

• Identifies new derivatives matching the provided criteria (or all new derivatives if no criteria provided)
• Sets isNewDerivative to false on each derivative
• Deletes underlying asset relationships
• Returns a summary of downgraded nodes and deleted relationships

Request body

The request accepts optional filter criteria to identify which derivatives to downgrade. If no criteria are provided, all new derivatives will be downgraded.

⚠️ The underlying_node filter is not supported for downgrade operations and will result in a 400 Bad Request error.

curl -X POST "https://{firm}.addepar.com/api/v1/derivatives/migration/downgrade" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "criteria": [
      {
        "type": "node_type",
        "value": "OPTION"
      }
    ]
  }'

HTTP/1.1 200

{
  "node_count": 3,
  "nodes_downgraded": [2001, 2002, 2003],
  "relationships_deleted": 3
}

Response fields

Response codes:

• 200 OK -- Success
• 400 Bad Request -- Invalid payload (e.g., underlying_node filter used, invalid filter criteria)
• 403 Forbidden -- Not permitted to make the request

📘 Related resources

Derivatives | Underlying Assets