---
title: "POST /addresses"
method: POST
path: "/addresses"
---

# POST /addresses

`POST /addresses`

## Request

- Base URL: `https://api.useanima.sh/v1`
- URL: `https://api.useanima.sh/v1/addresses`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

## Request body

- object: Input for creating a new address identity
  - `agentId` union, required: Agent identifier that owns this address
    - string
    - string
  - `type` 'BILLING' | 'SHIPPING' | 'MAILING' | 'REGISTERED', required: Type of address to create
  - `label` string: User-defined label for the address
  - `street1` string, required: Primary street address line
  - `street2` string: Secondary street address line (apt, suite, etc.)
  - `city` string, required: City name
  - `state` string, required: State or province
  - `postalCode` string, required: Postal or ZIP code
  - `country` string, required: 2-character ISO 3166-1 alpha-2 country code

## Response `200`

OK

- object: Full address identity record
  - `id` string, required: Unique address identity identifier
  - `agentId` string, required: Agent that owns this address
  - `orgId` string, required: Organization the address belongs to
  - `type` 'BILLING' | 'SHIPPING' | 'MAILING' | 'REGISTERED', required: Address type
  - `label` string, nullable, required: User-defined label
  - `street1` string, required: Primary street address line
  - `street2` string, nullable, required: Secondary street address line
  - `city` string, required: City name
  - `state` string, required: State or province
  - `postalCode` string, required: Postal or ZIP code
  - `country` string, required: 2-character ISO country code
  - `validated` boolean, required: Whether the address has been validated
  - `validatedAt` string, date-time, nullable, required: Timestamp when the address was validated
  - `provider` string, nullable, required: Validation provider name
  - `metadata` object, nullable, required: Additional metadata
  - `isPrimary` boolean, required: Whether this is the primary address for its type
  - `createdAt` string, date-time, required: Timestamp when the address was created
  - `updatedAt` string, date-time, required: Timestamp when the address was last updated

---

[API](https://skmtc.dev/useanima/apis/anima-api.md) · [All operations](https://skmtc.dev/useanima/apis/anima-api/llms.txt) · [OpenAPI document](https://skmtc.dev/useanima/apis/anima-api/revisions/aaa148188980?raw)