Contacts

Look up contacts by external reference

From a list of your references, says which ones already exist in Filmo and which do not.

POST

/api/v1/contacts/lookup

curl https://app.filmo.io/api/v1/contacts/lookup \
  --request POST \
  --header "Authorization: Bearer $FILMO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "references": [
    "ERP-CLI-0042",
    "ERP-CLI-0043",
    "ERP-CLI-9999"
  ]
}'

Node.jsfetch('https://app.filmo.io/api/v1/contacts/lookup', { method: 'POST', headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ references: ['ERP-CLI-0042', 'ERP-CLI-0043', 'ERP-CLI-9999'] }) })Pythonimport requests requests.post( "https://app.filmo.io/api/v1/contacts/lookup", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY", "Content-Type": "application/json" }, json={ "references": [ "ERP-CLI-0042", "ERP-CLI-0043", "ERP-CLI-9999" ] } )

{
  "data": {
    "contacts": [
      {
        "id": "contact_9f3a2b",
        "name": "Example contact",
        "contactNumber": "2026-0001"
      }
    ],
    "notFound": [
      "Example not found"
    ]
  }
}

{
  "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:read"
}

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

notFound are the ones to create. It is the primitive of any synchronization: without it, the alternative is one call per reference and guessing from the 404. It writes NOTHING, even though it is a POST: the list of references does not fit in a query string.

Authorizations

Bearer API key with the scope below. contacts:read

Body

application/json

Body schema: ContactsLookupBody

referencesstring[]Required

External references to look up. At least one, at most 200.

Limits: min 1 items, max 200 items, each min length 1

Response

application/json

Successful response.

Response schema: ContactsLookupResultDto

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

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

dataobject

Result of looking up contacts by external reference.

Show child attributes

data.contactsobject[]

Contacts that matched at least one reference.

Show child attributes

data.contacts.idstring

Identifier of the contact in Filmo.

data.contacts.namestring

Contact name.

data.contacts.contactNumberstring

Filmo contact number.

data.notFoundstring[]

References that did not match any contact. These are the ones to create.

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.

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

Was this page helpful?

Request examples

Authorizations

Body

Response

Errors

Deprecation

Related