TrustLayer contacts API
The contacts API from TrustLayer — 4 operation(s) for contacts.
OpenAPI Specification
openapi: 3.0.0
info:
title: TrustLayer Platform Auth contacts API
version: '1.0'
contact:
name: TrustLayer Support
email: support@trustlayer.io
termsOfService: https://trustlayer.io/terms-of-service
externalDocs:
description: OpenAPI specification
url: /v1/platform-api.yaml
description: '3rd-party API for the TrustLayer platform.
**Deprecated.** Platform API v1 is deprecated as of 01 June 2026 and is
scheduled for sunset (end-of-life) on 31 March 2027. It remains fully
available until the sunset date but will not receive new features. Please
migrate to Platform API v2 for new integrations.
All v1 responses carry the standard deprecation response headers
([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)):
```http
Deprecation: @1780272000
Sunset: Wed, 31 Mar 2027 23:59:59 GMT
Link: <https://developers.trustlayer.io/>; rel="deprecation", <https://developers.trustlayer.io/>; rel="sunset"
```
`Deprecation: @1780272000` is the Unix timestamp for 2026-06-01T00:00:00Z;
sunset (end-of-life) is 2027-03-31T23:59:59 GMT.'
x-deprecated: true
x-deprecation-date: '2026-06-01'
x-sunset: '2027-03-31'
license:
name: Apache 2.0
url: https://apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:4000/v1
description: Local
- url: https://api.trustlayer.io/v1
description: Production
security:
- API Key: []
tags:
- name: contacts
paths:
/contacts/{contactId}:
parameters:
- schema:
type: string
name: contactId
in: path
required: true
get:
summary: Fetch a party contact's information
tags:
- contacts
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/response-status'
data:
$ref: '#/components/schemas/contact'
required:
- status
- data
operationId: get-contacts-id
deprecated: true
description: 'Available include options:
* party'
parameters:
- $ref: '#/components/parameters/include'
patch:
summary: Update a party contact's information
operationId: patch-contacts-id
deprecated: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/response-status'
data:
$ref: '#/components/schemas/contact'
requestBody:
content:
application/json:
schema:
type: object
properties:
contact:
$ref: '#/components/schemas/contact-update'
description: 'Update a contact with the given data.
* setting the `primary` flag to `true` will remove it from the other contacts.
* setting the `primary` flag to `false` on the current primary contact will return a `400` response, since a primary contact must always exist.
* if given, `name` must be non-blank'
tags:
- contacts
parameters: []
x-internal: false
delete:
summary: Remove contact information from a party
operationId: delete-contacts-id
deprecated: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/response-status'
data:
$ref: '#/components/schemas/contact'
description: This will return a `400` response if you try to remove the primary contact.
tags:
- contacts
x-internal: false
/parties/{partyId}/contacts:
parameters:
- schema:
type: string
name: partyId
in: path
required: true
description: Party ID
post:
summary: Create a party contact
operationId: post-parties-id-contacts
deprecated: true
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/response-status'
data:
$ref: '#/components/schemas/party'
requestBody:
content:
application/json:
schema:
type: object
properties:
contact:
$ref: '#/components/schemas/contact-create'
description: '* `name` is required.
* setting the `primary` flag to `true` will unset it from the current primary contact.
'
x-internal: false
tags:
- contacts
get:
summary: List a party's contacts
operationId: get-parties-id-contacts
deprecated: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/response-status'
data:
type: array
items:
$ref: '#/components/schemas/contact'
meta:
$ref: '#/components/schemas/collection-meta'
description: Returns all the contacts for a party. Note that pagination is not available, so the meta information will always return the number of contacts in `totalCount` and 1 in `totalPages`.
tags:
- contacts
/contacts:
get:
tags:
- contacts
description: 'List contacts in the caller''s organization. Results are always scoped to the caller''s organization. Supports filtering, sorting, and pagination via `limit` and `skip`.
<!-- qs2mongo:list-summary -->
**Filtering**: `_id` (objectId), `createdAt` (date), `updatedAt` (date), `email` (string), `contactPersonName` (string), `companyName` (string). See "List Endpoints" in the API overview for operator syntax and combining rules.
**Sorting**: supported via `sort` (see the parameter''s description for allowed fields). Prefix with `-` for descending.
**Field projection**: supported via `fields` (see the parameter''s description for allowed fields).'
parameters:
- schema:
default: 20
type: integer
minimum: 0
exclusiveMinimum: true
maximum: 100
in: query
name: limit
required: false
- schema:
default: 0
type: integer
minimum: 0
maximum: 9007199254740991
in: query
name: skip
required: false
- schema:
type: string
minLength: 1
in: query
name: sort
required: false
description: 'Comma-separated list of fields to sort by. Example: ''_id,-createdAt''. Allowed: email, contactPersonName, companyName, createdAt, updatedAt'
- schema:
type: string
minLength: 1
in: query
name: fields
required: false
description: 'Comma-separated list of fields to project. Allowed: _id, email, contactPersonName, companyName, title, phone, fax, address, createdAt, updatedAt'
- schema:
type: string
in: query
name: _id
required: false
description: Filter by _id. 24-character hex ObjectId string (e.g. `_id=507f1f77bcf86cd799439011`). See "List Endpoints" in the API overview for operator syntax.
- schema:
type: string
in: query
name: createdAt
required: false
description: Filter by createdAt. ISO-8601 date or datetime string (e.g. `createdAt=2024-01-15`). See "List Endpoints" in the API overview for operator syntax.
- schema:
type: string
in: query
name: updatedAt
required: false
description: Filter by updatedAt. ISO-8601 date or datetime string (e.g. `updatedAt=2024-01-15`). See "List Endpoints" in the API overview for operator syntax.
- schema:
type: string
in: query
name: email
required: false
description: Filter by email. String value (e.g. `email=example`). See "List Endpoints" in the API overview for operator syntax.
- schema:
type: string
in: query
name: contactPersonName
required: false
description: Filter by contactPersonName. String value (e.g. `contactPersonName=example`). See "List Endpoints" in the API overview for operator syntax.
- schema:
type: string
in: query
name: companyName
required: false
description: Filter by companyName. String value (e.g. `companyName=example`). See "List Endpoints" in the API overview for operator syntax.
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
_id:
description: Unique identifier of the contact.
allOf:
- $ref: '#/components/schemas/objectId'
contactPersonName:
description: Full name of the contact person.
type: string
companyName:
description: Company or organization name for this contact.
type: string
title:
description: Job title of the contact person.
type: string
email:
description: Email address of the contact.
phone:
description: Phone number of the contact.
type: string
fax:
description: Fax number of the contact.
type: string
address:
description: Postal address of the contact. All sub-fields are optional.
type: object
properties:
type:
type: string
rawAddress:
type: string
line1:
type: string
line2:
type: string
postalCode:
type: string
city:
type: string
region:
type: string
country:
type: string
latitude:
type: number
longitude:
type: number
additionalProperties: false
createdAt:
description: Timestamp at which the contact was created.
type: string
format: date-time
updatedAt:
description: Timestamp at which the contact was last updated.
type: string
format: date-time
required:
- _id
additionalProperties: false
meta:
type: object
properties:
count:
type: number
description: Total number of records matching the query, across all pages.
next:
description: Relative URL for the next page of results, preserving filters/sort/projection. Omitted on the last page.
type: string
prev:
description: Relative URL for the previous page of results, preserving filters/sort/projection. Omitted on the first page.
type: string
required:
- count
additionalProperties: false
required:
- data
- meta
additionalProperties: false
'400':
description: The request could not be understood — invalid body payload, unknown querystring filter, or a schema validation failure.
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 400
applicationCode:
type: string
description: Machine-readable error code. For application errors this is the ApplicationError.applicationCode (e.g. "FLOW.006"); for schema validation failures it is "FLOW.002" (InvalidData); for unexpected server failures it is "LIB.000".
message:
type: string
description: Human-readable error message.
details:
description: Optional additional context about the error.
required:
- statusCode
- applicationCode
- message
additionalProperties: false
description: The request could not be understood — invalid body payload, unknown querystring filter, or a schema validation failure.
'401':
description: Authentication failed — the bearer token is missing, malformed, expired, or does not grant access to this resource.
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 401
applicationCode:
type: string
description: Machine-readable error code. For application errors this is the ApplicationError.applicationCode (e.g. "FLOW.006"); for schema validation failures it is "FLOW.002" (InvalidData); for unexpected server failures it is "LIB.000".
message:
type: string
description: Human-readable error message.
details:
description: Optional additional context about the error.
required:
- statusCode
- applicationCode
- message
additionalProperties: false
description: Authentication failed — the bearer token is missing, malformed, expired, or does not grant access to this resource.
'403':
description: The authenticated caller does not have permission to perform this action on the target resource.
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 403
applicationCode:
type: string
description: Machine-readable error code. For application errors this is the ApplicationError.applicationCode (e.g. "FLOW.006"); for schema validation failures it is "FLOW.002" (InvalidData); for unexpected server failures it is "LIB.000".
message:
type: string
description: Human-readable error message.
details:
description: Optional additional context about the error.
required:
- statusCode
- applicationCode
- message
additionalProperties: false
description: The authenticated caller does not have permission to perform this action on the target resource.
'404':
description: The requested resource does not exist or is not visible to the authenticated caller.
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 404
applicationCode:
type: string
description: Machine-readable error code. For application errors this is the ApplicationError.applicationCode (e.g. "FLOW.006"); for schema validation failures it is "FLOW.002" (InvalidData); for unexpected server failures it is "LIB.000".
message:
type: string
description: Human-readable error message.
details:
description: Optional additional context about the error.
required:
- statusCode
- applicationCode
- message
additionalProperties: false
description: The requested resource does not exist or is not visible to the authenticated caller.
'500':
description: The server encountered an unexpected failure while processing the request.
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 500
applicationCode:
type: string
description: Machine-readable error code. For application errors this is the ApplicationError.applicationCode (e.g. "FLOW.006"); for schema validation failures it is "FLOW.002" (InvalidData); for unexpected server failures it is "LIB.000".
message:
type: string
description: Human-readable error message.
details:
description: Optional additional context about the error.
required:
- statusCode
- applicationCode
- message
additionalProperties: false
description: The server encountered an unexpected failure while processing the request.
post:
tags:
- contacts
description: Create a new contact in the caller's organization. The owning organization is derived from the access token and cannot be set in the body. Returns the new contact's identifier.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
email:
description: Email address of the contact. Required. Normalized to lowercase; duplicate detection is case-insensitive.
type: string
contactPersonName:
description: Full name of the contact person.
type: string
companyName:
description: Company or organization name for this contact.
type: string
title:
description: Job title of the contact person.
type: string
phone:
description: Phone number of the contact.
type: string
fax:
description: Fax number of the contact.
type: string
address:
description: Postal address of the contact. All sub-fields are optional.
type: object
properties:
type:
type: string
rawAddress:
type: string
line1:
type: string
line2:
type: string
postalCode:
type: string
city:
type: string
region:
type: string
country:
type: string
latitude:
type: number
longitude:
type: number
required:
- email
additionalProperties: false
description: Request body for creating a contact. The owning organization is always derived from the caller's token and cannot be set here.
description: Request body for creating a contact. The owning organization is always derived from the caller's token and cannot be set here.
responses:
'201':
description: Identifier-only response returned by contact write operations.
content:
application/json:
schema:
type: object
properties:
_id:
description: Unique identifier of the contact.
allOf:
- $ref: '#/components/schemas/objectId'
required:
- _id
additionalProperties: false
description: Identifier-only response returned by contact write operations.
'400':
description: The request could not be understood — invalid body payload, unknown querystring filter, or a schema validation failure.
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 400
applicationCode:
type: string
description: Machine-readable error code. For application errors this is the ApplicationError.applicationCode (e.g. "FLOW.006"); for schema validation failures it is "FLOW.002" (InvalidData); for unexpected server failures it is "LIB.000".
message:
type: string
description: Human-readable error message.
details:
description: Optional additional context about the error.
required:
- statusCode
- applicationCode
- message
additionalProperties: false
description: The request could not be understood — invalid body payload, unknown querystring filter, or a schema validation failure.
'401':
description: Authentication failed — the bearer token is missing, malformed, expired, or does not grant access to this resource.
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 401
applicationCode:
type: string
description: Machine-readable error code. For application errors this is the ApplicationError.applicationCode (e.g. "FLOW.006"); for schema validation failures it is "FLOW.002" (InvalidData); for unexpected server failures it is "LIB.000".
message:
type: string
description: Human-readable error message.
details:
description: Optional additional context about the error.
required:
- statusCode
- applicationCode
- message
additionalProperties: false
description: Authentication failed — the bearer token is missing, malformed, expired, or does not grant access to this resource.
'403':
description: The authenticated caller does not have permission to perform this action on the target resource.
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 403
applicationCode:
type: string
description: Machine-readable error code. For application errors this is the ApplicationError.applicationCode (e.g. "FLOW.006"); for schema validation failures it is "FLOW.002" (InvalidData); for unexpected server failures it is "LIB.000".
message:
type: string
description: Human-readable error message.
details:
description: Optional additional context about the error.
required:
- statusCode
- applicationCode
- message
additionalProperties: false
description: The authenticated caller does not have permission to perform this action on the target resource.
'404':
description: The requested resource does not exist or is not visible to the authenticated caller.
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 404
applicationCode:
type: string
description: Machine-readable error code. For application errors this is the ApplicationError.applicationCode (e.g. "FLOW.006"); for schema validation failures it is "FLOW.002" (InvalidData); for unexpected server failures it is "LIB.000".
message:
type: string
description: Human-readable error message.
details:
description: Optional additional context about the error.
required:
- statusCode
- applicationCode
- message
additionalProperties: false
description: The requested resource does not exist or is not visible to the authenticated caller.
'500':
description: The server encountered an unexpected failure while processing the request.
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 500
applicationCode:
type: string
description: Machine-readable error code. For application errors this is the ApplicationError.applicationCode (e.g. "FLOW.006"); for schema validation failures it is "FLOW.002" (InvalidData); for unexpected server failures it is "LIB.000".
message:
type: string
description: Human-readable error message.
details:
description: Optional additional context about the error.
required:
- statusCode
- applicationCode
- message
additionalProperties: false
description: The server encountered an unexpected failure while processing the request.
/contacts/{id}:
get:
tags:
- contacts
description: Read a single contact by id, scoped to the caller's organization. Use the `fields` query parameter to limit the response to a projection of the contact.
parameters:
- schema:
type: string
minLength: 1
in: query
name: fields
required: false
description: 'Comma-separated list of fields to project. Allowed: _id, contactPersonName, companyName, title, email, phone, fax, address, createdAt, updatedAt'
- schema:
allOf:
- $ref: '#/components/schemas/objectIdInput'
in: path
name: id
required: true
description: Identifier of the contact to read.
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
_id:
description: Unique identifier of the contact.
allOf:
- $ref: '#/components/schemas/objectId'
contactPersonName:
description: Full name of the contact person.
type: string
companyName:
description: Company or organization name for this contact.
type: string
title:
description: Job title of the contact person.
type: string
email:
description: Email address of the contact.
phone:
description: Phone number of the contact.
type: string
fax:
description: Fax number of the contact.
type: string
address:
description: Postal address of the contact. All sub-fields are optional.
type: object
properties:
type:
type: string
rawAddress:
type: string
line1:
type: string
line2:
type: string
postalCode:
type: string
city:
type: string
region:
type: string
country:
type: string
latitude:
type: number
longitude:
type: number
additionalProperties: false
createdAt:
description: Timestamp at which the contact was created.
type: string
format: date-time
updatedAt:
description: Timestamp at which the contact was last updated.
type: string
format: date-time
required:
- _id
additionalProperties: false
'400':
description: The request could not be understood — invalid body payload, unknown querystring filter, or a schema validation failure.
content:
application/json:
schema:
type: object
properties:
statusCode:
type: number
enum:
- 400
applicationCode:
type: string
description: Machine-readable error code. For application errors this is the ApplicationError.applicationCode (e.g. "FLOW.006"); for schema validation failures it is "FLOW.002" (InvalidData); for unexpected server failures it is "LIB.000".
message:
type: string
description: Human-readable error message.
details:
description: Optional additional context about the error.
required:
- statusCode
- applicationCode
- message
additionalProperties: false
description: T
# --- truncated at 32 KB (88 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/trustlayer/refs/heads/main/openapi/trustlayer-contacts-api-openapi.yml