> ## Documentation Index > Fetch the complete documentation index at: https://docs.unifygtm.com/llms.txt > Use this file to discover all available pages before exploring further. # Create record > Create a new record. ## Overview The *create* method creates a new record in the specified object. This method will fail if any record already exists with conflicting unique values, which may or may not be the desired behavior depending on your use case. If you are not sure whether a record already exists with the same unique values, consider using the [upsert method](/developers/api/data/records/upsert) instead. ## Examples This creates a new company record: ```http Request theme={null} POST /objects/company/records { "name": "Unify", "domain": "unifygtm.com", "description": "A nice company with a top-notch API.", "status": "Active" } ``` ```json Response theme={null} { "status": "success", "data": { "object": "company", "id": "73fcb798-9ccd-4138-8f6a-9a801123783c", "created_at": "2025-09-04T01:23:45Z", "updated_at": "2025-09-04T01:23:45Z", "attributes": { "name": "Unify", "domain": "unifygtm.com", "description": "A nice company with a top-notch API.", "status": "Active" // ... } } } ``` This creates a new person record and links them to an existing company if it exists: ```http Request theme={null} POST /objects/person/records { "first_name": "Austin", "last_name": "Hughes", "email": "austinhughes@unifygtm.com", "title": "CEO", "company": { "match": { "domain": "unifygtm.com" } } } ``` ```json Response theme={null} { "status": "success", "data": { "object": "person", "id": "bf3f4d5e-c995-496f-8774-5a1c58d05197", "created_at": "2025-09-04T01:23:45Z", "updated_at": "2025-09-04T01:23:45Z", "attributes": { "first_name": "Austin", "last_name": "Hughes", "email": "austinhughes@unifygtm.com", "title": "CEO", "company": "73fcb798-9ccd-4138-8f6a-9a801123783c" // ... } } } ``` If a company with this domain does not exist, the `company` reference on this person will be `null`. If you want to create a company in that case instead, you can use a nested upsert: ```http Request theme={null} POST /objects/person/records { "first_name": "Austin", "last_name": "Hughes", "email": "austinhughes@unifygtm.com", "title": "CEO", "company": { "match": { "domain": "unifygtm.com" }, "create": { "name": "Unify", "domain": "unifygtm.com", "linkedin_url": "https://www.linkedin.com/company/unifygtm" } } } ``` ```json Response theme={null} { "status": "success", "data": { "object": "person", "id": "bf3f4d5e-c995-496f-8774-5a1c58d05197", "created_at": "2025-09-04T01:23:45Z", "updated_at": "2025-09-04T01:23:45Z", "attributes": { "first_name": "Austin", "last_name": "Hughes", "email": "austinhughes@unifygtm.com", "title": "CEO", "company": "73fcb798-9ccd-4138-8f6a-9a801123783c" // ... } } } ``` This creates a new record in a custom object called `product_user`: ```http Request theme={null} POST /objects/product_user/records { "user_id": "6b2a2761-3cbe-481f-8a1e-b24859c674f8", "full_name": "Bob Smith", "email_address": "bob.smith@gmail.com", "plan": "free_tier" } ``` ```json Response theme={null} { "status": "success", "data": { "object": "product_user", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "created_at": "2025-09-04T01:23:45Z", "updated_at": "2025-09-04T01:23:45Z", "attributes": { "user_id": "6b2a2761-3cbe-481f-8a1e-b24859c674f8", "full_name": "Bob Smith", "email_address": "bob.smith@gmail.com", "plan": "free_tier" // ... } } } ``` ## Usage ## OpenAPI ````yaml POST /objects/{object_name}/records openapi: 3.1.0 info: title: Unify Data API summary: Interact with objects, attributes, and records within the Unify platform. version: '1' termsOfService: https://www.unifygtm.com/legal/terms-and-conditions contact: name: Unify Support url: https://www.unifygtm.com/support email: support@unifygtm.com servers: - url: https://api.unifygtm.com/data/v1 variables: {} security: - ApiKeyAuth: [] tags: - name: Objects - name: Object Attributes - name: Object Attribute Options - name: Object Records paths: /objects/{object_name}/records: post: tags: - Object Records operationId: create_object_record parameters: - name: object_name in: path required: true schema: $ref: '#/components/schemas/UObjects.UObjectName' - name: validation_mode in: query required: false schema: $ref: '#/components/schemas/ValidationMode' explode: false requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRecordRequest' responses: '201': description: Response for a successful create operation. content: application/json: schema: type: object required: - status - data properties: status: type: string enum: - success data: type: object required: - object - id - created_at - updated_at - attributes properties: object: type: string description: >- The API name of the object this record is an instance of. readOnly: true id: allOf: - $ref: '#/components/schemas/UValues.UUuid' description: Unique UUID identifier for the record. readOnly: true created_at: type: string format: date-time description: Date and time the record was created. readOnly: true updated_at: type: string format: date-time description: Date and time the record was last updated. readOnly: true attributes: type: object unevaluatedProperties: anyOf: - $ref: '#/components/schemas/UValues.UValue' - type: 'null' description: >- Attribute values for the record. Each key is the API name of the attribute and each value is the corresponding attribute value for the record. description: Response for a successful create operation. '400': description: Response for any operation that results in a bad request error. content: application/json: schema: type: object required: - status properties: status: type: string enum: - bad_request - record_missing_required_field - referenced_record_not_found errors: type: array items: $ref: '#/components/schemas/UResponses.BadRequestError' message: type: string description: >- Response for any operation that results in a bad request error. '401': description: Response for any operation that results in an unauthorized error. content: application/json: schema: type: object required: - status - message properties: status: type: string enum: - unauthorized message: type: string description: >- Response for any operation that results in an unauthorized error. '404': description: Response for any operation that results in a not found error. content: application/json: schema: type: object required: - status - message properties: status: type: string enum: - object_not_found message: type: string description: Response for any operation that results in a not found error. '409': description: Response for any operation that results in a conflict error. content: application/json: schema: type: object required: - status - message properties: status: type: string enum: - record_conflict message: type: string description: Response for any operation that results in a conflict error. '500': description: Response for any operation that results in an internal server error. content: application/json: schema: type: object required: - status - message properties: status: type: string enum: - error message: type: string description: >- Response for any operation that results in an internal server error. '503': description: Response for any operation that results in service unavailability. content: application/json: schema: type: object required: - status - message properties: status: type: string enum: - service_unavailable message: type: string description: >- Response for any operation that results in service unavailability. components: schemas: UObjects.UObjectName: type: string ValidationMode: type: string enum: - strict - ignore_invalid description: >- Validation mode to use when validating request data. `strict` validation will fail requests if any attribute fails validation, including unrecognized attributes. `ignore_invalid` validation will strip out unknown attributes and replace known, non-required attributes with `undefined` if they fail validation. The request will still fail if the request body does not contain the proper structure or if any required attributes fail validation. CreateRecordRequest: type: object required: - data properties: data: type: object unevaluatedProperties: $ref: '#/components/schemas/UValues.UValue' description: |- The attribute values for the new record. All required attributes on the object must be included. description: Request body for creating a record. UValues.UUuid: type: string description: String UUIDv4 value. title: UUuid UResponses.BadRequestError: type: object required: - code properties: code: type: string path: type: array items: anyOf: - type: string - type: integer object_api_name: type: string attribute_api_name: type: string allOf: - type: object unevaluatedProperties: {} description: Validation error detail returned for bad request responses. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ````