Create Contact

POST

/public/v1/contacts

curl --request POST \
  --url https://api.aymaragents.com/public/v1/contacts \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "fullName": "example", "phone": "example", "email": "example", "country": "example" }'

• Producción

Create a contact, origin='api' always (SPEC_API_PUBLICA.md §2.2).

phone is the only required field, normalized to E.164. A phone/email already used by a live (or soft-deleted) contact of this tenant -> 409 ALREADY_EXISTS.

Idempotency-Key (API-3, D-API-4) is optional: a repeat with the SAME header and SAME body replays the original response without creating a second contact; the SAME header with a DIFFERENT body -> 422 IDEMPOTENCY_KEY_REUSE_MISMATCH.

---

Permiso necesario: tenant:contacts.manage

Authorizations

• ApiKeyAuth

Request Body^required

Media typeapplication/json

PublicContactCreateRequest

POST /public/v1/contacts body.

origin is NEVER accepted – the route always stamps 'api' server-side (SPEC_API_PUBLICA.md §2.2), not even a field on this model.

object

fullName

Any of:

string

string

null

null

phone

required

Phone

string

>= 1 characters

email

Any of:

string

string

null

null

country

Any of:

string

string

>= 2 characters <= 2 characters

null

null

Example^generated

{
  "fullName": "example",
  "phone": "example",
  "email": "example",
  "country": "example"
}

Responses

201

Successful Response

Media typeapplication/json

PublicContactOut

A single contact, curated subset of the internal CustomerOut.

Drops signingEmail (INT-PANDADOC-1 internal-integration concern, meaningless to a third party reading/writing contacts generically).

object

id

required

Id

string

fullName

Any of:

string

string

null

null

phone

Any of:

string

string

null

null

email

Any of:

string

string

null

null

country

Any of:

string

string

null

null

phoneVerifiedAt

Any of:

string

string

null

null

emailVerifiedAt

Any of:

string

string

null

null

marketingOptOut

required

Marketingoptout

boolean

marketingOptOutAt

Any of:

string

string

null

null

origin

required

Origin

string

createdAt

required

Createdat

string

Example^generated

{
  "id": "example",
  "fullName": "example",
  "phone": "example",
  "email": "example",
  "country": "example",
  "phoneVerifiedAt": "example",
  "emailVerifiedAt": "example",
  "marketingOptOut": true,
  "marketingOptOutAt": "example",
  "origin": "example",
  "createdAt": "example"
}

422

Validation Error

Media typeapplication/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

input

Input

ctx

Context

object

Example^generated

{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}