Account Holders

Create account holder

Changed on

Creates a new account holder and starts asynchronous processing.

post/v1/account_holders

Request

  • Base URL
    https://api.augustus.com
  • URL
    https://api.augustus.com/v1/account_holders
  • Auth
    HTTP bearer

Headers

Idempotency-Keystring required

Idempotency key for safe retries. Reusing a key with an identical request body returns the cached response. Reusing a key with a different body returns 409.

Request body

account_program_idstring uuid required

ID of the account program to create the account holder under.

holder_type'natural_person' | 'business' required

Type of the account holder.

metadataobject nullable

Set of up to 50 key-value string pairs you can attach to store structured information, such as correlating this resource with an object in your own system. Keys may be up to 40 characters and values up to 500 characters.

Example request

{
  "account_program_id": "550e8400-e29b-41d4-a716-446655440002",
  "beneficiary_data": {
    "legal_name": "Jordan Rivera",
    "residential_address": {
      "line_1": "548 Market St",
      "line_2": "Apartment 4B",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94103"
    },
    "date_of_birth": "1990-01-15",
    "identification": {
      "value": "123-45-6789"
    }
  },
  "metadata": {
    "invoice_id": "INV-2026-0042"
  }
}

Response

Account holder created successfully

idstring required

Unique identifier of the account holder.

type'account_holder' required

Resource type discriminator.

holder_type'natural_person' | 'business' required

Type of the account holder.

status'pending' | 'active' | 'closed' required

Current account holder status.

metadataobject required

Set of up to 50 key-value string pairs you can attach to store structured information, such as correlating this resource with an object in your own system. Keys may be up to 40 characters and values up to 500 characters.

created_atstring date-time required

ISO 8601 UTC timestamp when the account holder was created.

Example response

{
  "id": "68e0a1b2c3d4e5f60718293a",
  "beneficiary_data": {
    "legal_name": "Jordan Rivera",
    "residential_address": {
      "line_1": "548 Market St",
      "line_2": "Apartment 4B",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94103"
    },
    "date_of_birth": "1990-01-15",
    "identification": {
      "value": "123-45-6789"
    }
  },
  "metadata": {
    "invoice_id": "INV-2026-0042"
  },
  "created_at": "2026-01-15T10:30:00Z"
}

Changes

  • f7ded6c181abRevision changes
    • info

      endpoint added

  • 8e304f78f67eRevision changes
    • breaking

      removed from the /////////// request property anyOf list

    • breaking

      removed from the /////////// request property anyOf list

    • breaking

      removed from the ///// request property anyOf list

    • breaking

      removed from the ///// request property anyOf list

    • breaking

      removed from the ///// request property anyOf list

    • breaking

      removed from the ///// request property anyOf list

    • breaking

      removed subschema #1 subschema #2 from the ///// request property anyOf list

    • info

      added to the /////////// request property anyOf list

    • info

      added to the /////////// request property anyOf list

    • info

      added to the ///// request property anyOf list

    • info

      added to the ///// request property anyOf list

    • info

      added to the ///// request property anyOf list

    • info

      added to the ///// request property anyOf list

    • info

      added subschema #1 subschema #2 to the ///// request property anyOf list

    • info

      the request property ///// became optional

    • info

      added subschema #1 subschema #2 to the ///// response property anyOf list for the response status

    • info

      removed subschema #1 subschema #2 from the ///// response property anyOf list for the response status