Parties

These source writes require source:sync. For a service-account or organization-app token, initialize Sync Sources for each entity first, then include the top-level entity selector shown below. Entity apps omit entity and use their authorized connection. See Working across an organization.

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 zero 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

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

Response

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

{
  "parties": [
    {
      "digitsId": "650e5809-13ba-4869-945f-b8604181a250",
      "externalId": "customer_123",
      "name": "Acme Corporation"
    },
    {
      "digitsId": "d24c2e5f-3a4f-4b8b-bc6f-6b4fe77597f1",
      "externalId": "contractor_456",
      "name": "Jane Smith"
    }
  ]
}

Idempotence

The sync endpoint is idempotent based on the externalId field:

First sync: Creates a new party in Digits
Subsequent syncs: Updates the existing party with the same externalId
Identifier scoping: Party external IDs are scoped to the connection’s source data for the selected entity, so different entity connections can use the same ID values

Using Parties in Transactions

Once synced, you can reference parties in transactions using their external IDs. Transaction references use an Identifier object:

{
  "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