Parties

Parties represent people or businesses that transact with your entity, such as customers, vendors, contractors, or employees.

Syncing Parties

Use the party sync endpoint to create, update, and delete parties in batch.

📘

Parties are merged in the Ledger

For example, if two parties are synced from two sources with the same name, they will be merged to become the same Party within the ledger.

Unused parties (parties with 0 transactions) are automatically excluded from the ledger on merge.

Request Example

POST https://connect.digits.com/v1/source/parties
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "parties": [
    {
      "externalId": {
        "issuer": "yourapp.com",
        "id": "customer_123"
      },
      "name": "Acme Corporation",
      "email": "[email protected]",
      "kind": "Business",
      "description": "Primary vendor"
    },
    {
      "externalId": {
        "issuer": "yourapp.com",
        "id": "contractor_456"
      },
      "name": "Jane Smith",
      "email": "[email protected]",
      "kind": "Person"
    }
  ]
}

Response

The response returns an array of EntityParty objects that map your external IDs to Digits IDs:

{
  "parties": [
    {
      "digitsId": "650e5809-13ba-4869-945f-b8604181a250",
      "externalId": "customer_123",
      "name": "Acme Corporation"
    },
    {
      "digitsId": "650e5809-13ba-4869-945f-b8604181a250",
      "externalId": "contractor_456",
      "name": "Jane Smith"
    }
  ]
}

Idempotence

The sync endpoint is idempotent based on the external_id field:

• First sync: Creates a new party in Digits
• Subsequent syncs: Updates the existing party with the same external_id
• Identifier scoping: External IDs are scoped to your source, so different sources can use the same ID values

Using Parties in Transactions

Once synced, you can reference parties in transactions using their external IDs:

{
  "counterparty": {
    "externalId": {
      "issuer": "yourapp.com",
      "id": "customer_123"
    }
  }
}

You can also reference parties at the entry level for more granular control.

Best Practices

• Sync parties before transactions: Ensure all parties are synced before referencing them in transactions
• Batch operations: Send multiple parties in a single request for better performance
• Update on change: Re-sync parties whenever their information changes in your source system