Contacts

Create a contact

Creates a contact with domain validation (email, NIF, field allow-list).

POST

/api/v1/contacts

curl https://app.filmo.io/api/v1/contacts \
  --request POST \
  --header "Authorization: Bearer $FILMO_API_KEY" \
  --header "Idempotency-Key: $(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Producciones Delta S.L.",
  "contactType": "company",
  "role": "client",
  "nif": "00000000T",
  "email": "hola@example.com",
  "phone": "+34 600 000 000",
  "addressLine1": "Calle de la Cámara 12",
  "city": "Madrid",
  "province": "Madrid",
  "postcode": "28001",
  "country": "ES",
  "preferredLanguage": "es-ES",
  "currency": "EUR"
}'

Node.jsfetch('https://app.filmo.io/api/v1/contacts', { method: 'POST', headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Producciones Delta S.L.', contactType: 'company', role: 'client', nif: '00000000T', email: 'hola@example.com', phone: '+34 600 000 000', addressLine1: 'Calle de la Cámara 12', city: 'Madrid', province: 'Madrid', postcode: '28001', country: 'ES', preferredLanguage: 'es-ES', currency: 'EUR' }) })Pythonimport uuid import requests requests.post("https://app.filmo.io/api/v1/contacts", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json" }, json={ "name": "Producciones Delta S.L.", "contactType": "company", "role": "client", "nif": "00000000T", "email": "hola@example.com", "phone": "+34 600 000 000", "addressLine1": "Calle de la Cámara 12", "city": "Madrid", "province": "Madrid", "postcode": "28001", "country": "ES", "preferredLanguage": "es-ES", "currency": "EUR" } )

{
  "data": {
    "id": "contact_9f3a2b",
    "name": "Example contact",
    "contactType": "person",
    "role": "client",
    "status": "active",
    "nif": "B00000000",
    "commercialName": "Example commercial name",
    "position": "Example position",
    "contactNumber": "2026-0001",
    "emails": [
      {
        "id": "email_9f3a2b",
        "label": "Main",
        "email": "ana.garcia@example.com",
        "isPrimary": true
      }
    ],
    "billingEmail": "ana.garcia@example.com",
    "phoneNumbers": [
      {
        "id": "phone_number_9f3a2b",
        "label": "Main",
        "number": "+34 600 000 000",
        "countryCode": "+34",
        "isPrimary": true
      }
    ],
    "websites": [
      {
        "id": "website_9f3a2b",
        "label": "Main",
        "url": "https://example.com/resource"
      }
    ],
    "addresses": [
      {
        "id": "address_9f3a2b",
        "label": "Main",
        "addressLine1": "Calle de Ejemplo 12",
        "addressLine2": "Calle de Ejemplo 12",
        "city": "Madrid",
        "province": "Madrid",
        "postcode": "28001",
        "country": "ES",
        "isMain": true
      }
    ],
    "folder": "Example folder",
    "discountPercentage": 1,
    "preferredLanguage": "es-ES",
    "currency": "EUR",
    "paymentMethod": {
      "type": "bank_transfer",
      "customValue": "Example custom value"
    },
    "paymentDays": [
      1
    ],
    "expirationDays": 1,
    "subscribedToMarketing": true,
    "isAppUser": true,
    "customFields": {
      "example": "example"
    },
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-09-01T08:00:00.000Z",
    "relatedContacts": [
      {
        "id": "related_contact_9f3a2b",
        "name": "Example related contact",
        "commercialName": "Example commercial name",
        "contactType": "person",
        "role": "client",
        "status": "active",
        "relationRole": "Example relation role"
      }
    ]
  }
}

{
  "type": "https://docs.filmo.io/errors/validation_error",
  "title": "Validation error",
  "status": 400,
  "code": "validation_error",
  "detail": "2 validation errors",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "name",
      "code": "too_small",
      "message": "Must be at least 1 characters long"
    },
    {
      "path": "contactType",
      "code": "invalid_value",
      "message": "Value not allowed; expected company, person"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Missing Authorization header: Bearer <api key>",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API key does not have the required scope (orders:write)",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "requiredScope": "contacts:write"
}

{
  "type": "https://docs.filmo.io/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "Resource not found",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "code": "conflict",
  "detail": "The current state of the resource does not allow the operation",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "",
      "code": "invalid_state",
      "message": "The current state of the resource does not allow the operation"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/precondition_failed",
  "title": "Precondition failed",
  "status": 412,
  "code": "precondition_failed",
  "detail": "The resource changed since you read it: read it again and retry",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/idempotency_key_reused",
  "title": "Idempotency-Key reused",
  "status": 422,
  "code": "idempotency_key_reused",
  "detail": "The Idempotency-Key header was already used with a different body",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limited",
  "detail": "Rate limit exceeded: retry in 30 seconds",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "retryAfter": 30
}

{
  "type": "https://docs.filmo.io/errors/internal_error",
  "title": "Internal error",
  "status": 500,
  "code": "internal_error",
  "detail": "Internal error",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

Generated from the schema

Returns the created contact in detail.

Authorizations

Bearer API key with the scope below. contacts:write

Headers

Idempotency-Keystring

Unique identifier of the request, chosen by the client (a UUID works). Between 1 and 255 characters: an empty header is rejected with 400 validation_error, because the client would believe itself protected. Repeating the same key with the SAME body within 24 h returns the stored response without executing again, with the Idempotent-Replay: true header. With a DIFFERENT body it returns 422. It is the safe way to retry after a network timeout.

Limits: min length 1, max length 255

Example:"9f1c2f4e-3a5b-4f6d-8e7a-0b1c2d3e4f5a"

If-Matchstring

Optimistic locking: the ETag you read from the resource (or *). If the resource changed since, the write is rejected with 412 precondition_failed before doing anything; read it again and retry. Without the header the write always proceeds.

Example:"\"3sT3d9pBvZq4h2N0w8x1YkLmQ7c\""

Body

application/json

Body schema: ContactCreateBody

namestringRequired

Contact name (person or company). Required.

Limits: min length 1, max length 200

contactTypestring

Contact type: person (individual) or company (business).

Available options: person, company

rolestring

Contact role: client, provider, lead, debtor, creditor, student, teacher or unspecified.

Available options: client, provider, lead, debtor, creditor, student, teacher, unspecified

nifstring

NIF/CIF or tax identification number of the contact.

Limits: max length 20

commercialNamestring

Trade name, if it differs from the legal name.

Limits: max length 200

positionstring

Job title or position of the contact person.

Limits: max length 200

emailstring<email>

Contact email address; the format is validated.

Limits: max length 200

phonestring

Contact phone number.

Limits: max length 50

addressLine1string

First line of the address (street and number).

Limits: max length 300

addressLine2string

Second line of the address (floor, door, etc.).

Limits: max length 300

citystring

City of the address.

Limits: max length 200

provincestring

Province or region of the address.

Limits: max length 200

postcodestring

Postcode of the address.

Limits: max length 20

countrystring

Country of the address (code or short name).

Limits: max length 10

folderstring

Folder or organizational grouping of the contact.

Limits: max length 200

contactNumberstring

Contact number assigned by the account (internal reference).

Limits: max length 50

preferredLanguagestring

Preferred language of the contact for communications and documents.

Available options: es-ES, en-US, fr-FR, ca-ES, de-DE, pl-PL

currencystring

Default currency of the contact as a 3-letter ISO 4217 code (e.g. "EUR").

Limits: min length 3, max length 3

subscribedToMarketingboolean

Whether the contact is subscribed to marketing communications.

Response

application/json

Successful response.

Response schema: ContactDetailDto

Envelope: ContactDetailResponse. meta.warnings is present only when the operation is deprecated.

Headers: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · ETag · Idempotent-Replay

dataobject

The contact in full, as returned by the API.

Show child attributes

data.idstring

Unique identifier of the contact.

data.namestring

Contact name (person or company).

data.contactTypestring

Contact type: person (individual) or company (business).

Available options: person, company

data.rolestring

Contact role: client, provider, lead, debtor, creditor, student, teacher or unspecified.

Available options: client, provider, lead, debtor, creditor, student, teacher, unspecified

data.statusstring

Contact status: active (operational), inactive (deactivated) or archived (closed, kept for historical records).

Available options: active, inactive, archived

data.nifstring | null

NIF/CIF or tax identification number; null if not recorded.

data.commercialNamestring | null

Trade name; null if it matches the name or is not recorded.

data.positionstring | null

Job title or position of the contact person; null if not recorded.

data.contactNumberstring | null

Contact number assigned by the account (internal reference); null if not recorded.

data.emailsobject[]

List of email addresses of the contact.

Show child attributes

data.emails.idstring

Internal identifier of the email within the contact.

data.emails.labelstring | null

Descriptive label of the email; null if it has none.

data.emails.emailstring

Email address.

data.emails.isPrimaryboolean

Whether this is the primary email of the contact.

data.billingEmailstring | null

Dedicated billing email; null means the primary email is used.

data.phoneNumbersobject[]

List of phone numbers of the contact.

Show child attributes

data.phoneNumbers.idstring

Internal identifier of the phone number within the contact.

data.phoneNumbers.labelstring | null

Descriptive label of the phone number; null if it has none.

data.phoneNumbers.numberstring

Phone number.

data.phoneNumbers.countryCodestring | null

International country calling code (e.g. "+34"); null if not recorded.

data.phoneNumbers.isPrimaryboolean

Whether this is the primary phone number of the contact.

data.websitesobject[]

List of websites of the contact.

Show child attributes

data.websites.idstring

Internal identifier of the website within the contact.

data.websites.labelstring | null

Descriptive label of the website; null if it has none.

data.websites.urlstring

Website URL.

data.addressesobject[]

List of addresses of the contact.

Show child attributes

data.addresses.idstring

Internal identifier of the address within the contact.

data.addresses.labelstring | null

Descriptive label of the address; null if it has none.

data.addresses.addressLine1string | null

First line of the address; null if not recorded.

data.addresses.addressLine2string | null

Second line of the address; null if not recorded.

data.addresses.citystring | null

City; null if not recorded.

data.addresses.provincestring | null

Province or region; null if not recorded.

data.addresses.postcodestring | null

Postcode; null if not recorded.

data.addresses.countrystring | null

Country; null if not recorded.

data.addresses.isMainboolean

Whether this is the main address of the contact.

data.folderstring | null

Folder or organizational grouping; null if the contact is not classified.

data.discountPercentagenumber | null

General discount percentage of the contact (0-100); null if no discount is configured.

data.preferredLanguagestring | null

Preferred language of the contact; null if not recorded.

data.currencystring | null

Default currency of the contact as an ISO 4217 code; null if not recorded.

data.paymentMethodobject | null

Preferred payment method of the contact; null if not configured.

Show child attributes

data.paymentMethod.typestring

Payment method type: bank_transfer, card, cash, sepa_direct_debit or other.

Available options: bank_transfer, card, cash, other, sepa_direct_debit

data.paymentMethod.customValuestring | null

Free-text detail when the type is "other" (for example a method recorded before it was configured); null otherwise.

data.paymentDaysinteger[] | null

Days of the month on which the contact makes payments; null if not configured.

data.expirationDaysinteger | null

Default due days for the invoices of the contact; null if not configured.

data.subscribedToMarketingboolean

Whether the contact is subscribed to marketing communications.

data.isAppUserboolean

Whether the contact has access to the app.

data.customFieldsobject<string, any>

Custom field values by custom field identifier; the definitions are in /api/v1/custom-fields.

data.createdAtstring<date-time>

Creation date in ISO 8601 with offset.

data.updatedAtstring<date-time>

Last update date in ISO 8601 with offset.

data.relatedContactsobject[]

Contacts related to this contact (e.g. people of a company).

Show child attributes

data.relatedContacts.idstring

Unique identifier of the related contact.

data.relatedContacts.namestring

Name of the related contact.

data.relatedContacts.commercialNamestring | null

Trade name of the related contact; null if not recorded.

data.relatedContacts.contactTypestring

Type of the related contact: person or company.

Available options: person, company

data.relatedContacts.rolestring

Role of the related contact.

Available options: client, provider, lead, debtor, creditor, student, teacher, unspecified

data.relatedContacts.statusstring

Status of the related contact: active, inactive or archived.

Available options: active, inactive, archived

data.relatedContacts.relationRolestring | null

Role of the relationship between the two contacts (e.g. "employee of"); null if not recorded.

metaobject

Additional information about the response.

Show child attributes

meta.warningsobject[]

Lifecycle warnings; present only when the operation is deprecated.

Show child attributes

meta.warnings.codestring

Stable warning code.

Available options: deprecated

meta.warnings.messagestring

For people: what is deprecated, until when, and what to use.

meta.warnings.sunsetstring

Day (YYYY-MM-DD) the operation stops being served.

meta.warnings.replacementstring | null

operationId of the operation to use instead, or null if there is none.

meta.warnings.linkstring

Where the deprecation is documented (the changelog).

Errors

Status	Codes	Meaning
400	`validation_error`	Malformed query or body. `errors[]` lists every offending field with its stable code.
404	`not_found`	It does not exist or is outside the scope of the API key.
409	`conflict`	The current state of the resource prevents the operation, a request with that Idempotency-Key is already in progress, or another conditional write (`If-Match`) held the resource for more than five seconds. `errors[0].code` says which: `in_progress` and `lock_timeout` are solved by retrying; `invalid_state` is not, because the state of the resource forbids the operation.
412	`precondition_failed`	The `If-Match` entity tag does not match the current representation. Read the resource again and retry.
422	`idempotency_key_reused`	The same key was used before with a different body. Change the key.

401, 403, 429, 500 can be returned by any operation. Errors

Deprecation

This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date. Versioning policy

CRM
Contact
The contact, as returned by the API.

Was this page helpful?

Request examples

Authorizations

Headers

Body

Response

Errors

Deprecation

Related

Related pages

Contact