TrustLayer Primary Records API
The Primary Records API from TrustLayer — 12 operation(s) for primary records.
OpenAPI Specification
openapi: 3.0.0
info:
title: TrustLayer Platform Auth Primary Records 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: Primary Records
description: ''
paths:
/primary-records:
get:
tags:
- Primary Records
description: 'List primary records in the caller''s organization. Results are always scoped to the caller''s organization. Supports pagination via `limit` and `skip`.
<!-- qs2mongo:list-summary -->
**Filtering**: `_id` (objectId), `createdAt` (date), `updatedAt` (date), `primaryObjectId` (objectId), `typeId` (objectId), `name` (string), `status` (string), `externalCodes` (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: typeId, status, name, additionalNotes, createdAt, updatedAt, website, portalMessage'
- schema:
type: string
minLength: 1
in: query
name: fields
required: false
description: 'Comma-separated list of fields to project. Allowed: _id, organization, primaryObjectId, typeId, status, name, address, automationsEnabled, externalCodes, additionalNotes, createdAt, updatedAt, website, portalMessage, computedAttributes, contacts'
- 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: primaryObjectId
required: false
description: Filter by primaryObjectId. 24-character hex ObjectId string (e.g. `primaryObjectId=507f1f77bcf86cd799439011`). See "List Endpoints" in the API overview for operator syntax.
- schema:
type: string
in: query
name: typeId
required: false
description: Filter by typeId. 24-character hex ObjectId string (e.g. `typeId=507f1f77bcf86cd799439011`). See "List Endpoints" in the API overview for operator syntax.
- schema:
type: string
in: query
name: name
required: false
description: Filter by name. String value (e.g. `name=example`). See "List Endpoints" in the API overview for operator syntax.
- schema:
type: string
in: query
name: status
required: false
description: Filter by status. String value (e.g. `status=example`). See "List Endpoints" in the API overview for operator syntax.
- schema:
type: string
in: query
name: externalCodes
required: false
description: Filter by externalCodes. String value (e.g. `externalCodes=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 primary record.
allOf:
- $ref: '#/components/schemas/objectId'
organization:
description: Identifier of the organization (workspace) that owns the primary record. Always equal to the caller's organization.
allOf:
- $ref: '#/components/schemas/objectId'
primaryObjectId:
description: Identifier of the primary object (entity type) this record belongs to. See `/v2/primary-objects`.
allOf:
- $ref: '#/components/schemas/objectId'
typeId:
description: Optional identifier of the record type within the primary object.
allOf:
- $ref: '#/components/schemas/objectId'
status:
type: string
enum:
- active
- archived
description: Lifecycle status of the primary record. Defaults to `active` on creation.
name:
description: Human-readable name of the primary record.
type: string
minLength: 1
address:
type: object
properties:
raw:
type: string
minLength: 1
line1:
type: string
minLength: 1
line2:
type: string
minLength: 1
postalCode:
type: string
city:
type: string
minLength: 1
region:
type: string
minLength: 1
country:
type: string
minLength: 1
latitude:
type: number
longitude:
type: number
additionalProperties: false
description: Postal address of the primary record. All sub-fields are optional; provide only what is known.
automationsEnabled:
type: array
items:
$ref: '#/components/schemas/objectId'
description: Identifiers of automations enabled for this primary record.
externalCodes:
type: array
items:
type: string
minLength: 1
description: External identifiers (e.g. ERP / accounting codes) attached to this primary record.
additionalNotes:
description: Free-form notes about the primary record.
createdAt:
description: Timestamp at which the primary record was created.
type: string
format: date-time
updatedAt:
description: Timestamp at which the primary record was last updated.
type: string
format: date-time
website:
description: Website URL for the primary record.
nullable: true
type: string
portalMessage:
description: Custom message shown to external parties on this primary record's portal page. Stored and returned as the raw value; template placeholders (e.g. {{primaryRecord.name}}) are not resolved by this API.
type: string
minLength: 1
computedAttributes:
type: object
properties:
documentsCount:
type: number
description: Total number of documents currently associated with this primary record.
nonResponsiveSince:
description: Timestamp at which the primary record was first considered non-responsive to compliance requests, if applicable.
type: string
format: date-time
lastMessageSentOn:
description: Timestamp of the most recent compliance request message sent to this primary record, if any.
type: string
format: date-time
required:
- documentsCount
additionalProperties: false
description: Server-computed, read-only attributes derived from the primary record and its related compliance data. Not writable via this API.
contacts:
type: array
items:
type: object
properties:
email:
description: Email address of the contact.
contactPersonName:
description: Display name of the contact person.
type: string
primary:
type: boolean
description: Whether this contact is the primary point of contact for the record.
required:
- primary
additionalProperties: false
description: Read-only summary of the contacts attached to this primary record. To manage contacts use the `/v2/primary-records/:id/contacts` endpoints.
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:
- Primary Records
description: Create a new primary record in the caller's organization. The owning organization is derived from the access token. Returns the new record's identifier.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
primaryObjectId:
description: Identifier of the primary object (entity type) this record belongs to. See `/v2/primary-objects`.
allOf:
- $ref: '#/components/schemas/objectIdInput'
typeId:
description: Optional identifier of the record type within the primary object.
allOf:
- $ref: '#/components/schemas/objectIdInput'
status:
default: active
description: Lifecycle status of the primary record. Defaults to `active` on creation.
type: string
enum:
- active
- archived
name:
description: Human-readable name of the primary record.
type: string
minLength: 1
address:
type: object
properties:
raw:
type: string
minLength: 1
line1:
type: string
minLength: 1
line2:
type: string
minLength: 1
postalCode:
type: string
city:
type: string
minLength: 1
region:
type: string
minLength: 1
country:
type: string
minLength: 1
latitude:
type: number
longitude:
type: number
description: Postal address of the primary record. All sub-fields are optional; provide only what is known.
automationsEnabled:
default: []
description: Identifiers of automations enabled for this primary record.
type: array
items:
$ref: '#/components/schemas/objectIdInput'
externalCodes:
default: []
description: External identifiers (e.g. ERP / accounting codes) attached to this primary record.
type: array
items:
type: string
minLength: 1
additionalNotes:
description: Free-form notes about the primary record.
type: string
minLength: 1
website:
description: Website URL for the primary record.
nullable: true
type: string
portalMessage:
description: Custom message shown to external parties on this primary record's portal page. Stored and returned as the raw value; template placeholders (e.g. {{primaryRecord.name}}) are not resolved by this API.
type: string
minLength: 1
required:
- primaryObjectId
description: Request body for creating a primary record. The owning organization is always derived from the caller's token and cannot be set here.
description: Request body for creating a primary record. The owning organization is always derived from the caller's token and cannot be set here.
responses:
'201':
description: Identifier-only response. Returned when an endpoint mutates a primary record but does not need to return the full document.
content:
application/json:
schema:
type: object
properties:
_id:
description: Unique identifier of the primary record.
allOf:
- $ref: '#/components/schemas/objectId'
required:
- _id
additionalProperties: false
description: Identifier-only response. Returned when an endpoint mutates a primary record but does not need to return the full document.
'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.
/primary-records/{id}:
get:
tags:
- Primary Records
description: Read a single primary record by id, scoped to the caller's organization. Use the `fields` query parameter to limit the response to a projection of the record.
parameters:
- schema:
type: string
minLength: 1
in: query
name: fields
required: false
description: 'Comma-separated list of fields to project. Allowed: _id, organization, primaryObjectId, typeId, status, name, address, automationsEnabled, externalCodes, additionalNotes, createdAt, updatedAt, website, portalMessage, computedAttributes, contacts'
- schema:
allOf:
- $ref: '#/components/schemas/objectIdInput'
in: path
name: id
required: true
description: Identifier of the primary record to read.
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
_id:
description: Unique identifier of the primary record.
allOf:
- $ref: '#/components/schemas/objectId'
organization:
description: Identifier of the organization (workspace) that owns the primary record. Always equal to the caller's organization.
allOf:
- $ref: '#/components/schemas/objectId'
primaryObjectId:
description: Identifier of the primary object (entity type) this record belongs to. See `/v2/primary-objects`.
allOf:
- $ref: '#/components/schemas/objectId'
typeId:
description: Optional identifier of the record type within the primary object.
allOf:
- $ref: '#/components/schemas/objectId'
status:
type: string
enum:
- active
- archived
description: Lifecycle status of the primary record. Defaults to `active` on creation.
name:
description: Human-readable name of the primary record.
type: string
minLength: 1
address:
# --- truncated at 32 KB (318 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/trustlayer/refs/heads/main/openapi/trustlayer-primary-records-api-openapi.yml