## Create a contact
**post** `/v1/contacts`
Creates a new contact record.
After creation, Lightfield automatically enriches the contact in the background unless `skipEnrichment` is true. Enrichment is a metered event, so when bulk-loading 50 or more records that do not require additional enrichment, we recommend setting `skipEnrichment` to true.
Supports idempotency via the `Idempotency-Key` header.
To avoid duplicates, we recommend a find-or-create pattern — use [list filtering](/using-the-api/list-endpoints/#filtering) to check if a record exists before creating.
**[Required scope](/using-the-api/scopes/):** `contacts:create`
**[Rate limit category](/using-the-api/rate-limits/):** Write
### Body Parameters
- `fields: object { "$email", "$name", "$profilePhotoUrl" } or map[string or number or boolean or 3 more]`
Field values for the new contact. System fields use a `$` prefix (e.g. `$email`, `$name`); custom attributes use their bare slug. Note: `$name` is an object `{ firstName, lastName }`, not a plain string. Call the [definitions endpoint](/api/resources/contact/methods/definitions) to discover available fields and their types. See [Fields and relationships](/using-the-api/fields-and-relationships/) for value type details.
Read definitions for the object type’s configured `$pipeline` and `$stage` fields and options. See [Pipelines and stages](/using-the-api/fields-and-relationships/#pipelines-and-stages) for write rules.
- `Typed object { "$email", "$name", "$profilePhotoUrl" }`
- `"$email": optional array of string`
List of email addresses for the contact (`EMAIL`, multi-value).
- `"$name": optional object { firstName, lastName }`
The contact's name. Unlike other resources, this is an object: `{ firstName?: string, lastName?: string }`, not a plain string.
- `firstName: optional string`
The contact's first name.
- `lastName: optional string`
The contact's last name.
- `"$profilePhotoUrl": optional string`
URL of the contact's profile photo (`URL`).
- `Untyped = map[string or number or boolean or 3 more]`
- `string`
- `number`
- `boolean`
- `array of string`
- `Address object { city, country, latitude, 5 more }`
- `city: optional string`
City name.
- `country: optional string`
2-letter ISO 3166-1 alpha-2 country code.
- `latitude: optional number`
Latitude coordinate.
- `longitude: optional number`
Longitude coordinate.
- `postalCode: optional string`
Postal or ZIP code.
- `state: optional string`
State or province.
- `street: optional string`
Street address line 1.
- `street2: optional string`
Street address line 2.
- `FullName object { firstName, lastName }`
- `firstName: optional string`
The contact's first name.
- `lastName: optional string`
The contact's last name.
- `relationships: optional object { "$account", "$files" } or map[string or array of string]`
Relationships to set on the new contact. System relationships use a `$` prefix (e.g. `$account`); custom relationships use their bare slug. Each value is a single entity ID or an array of IDs. Call the [definitions endpoint](/api/resources/contact/methods/definitions) to list available relationship keys.
- `Typed object { "$account", "$files" }`
- `"$account": optional string or array of string`
ID(s) of accounts to associate with this contact.
- `string`
- `array of string`
- `"$files": optional string or array of string`
File ID(s) to attach to this contact. Files must be in `completed` status.
- `string`
- `array of string`
- `Untyped = map[string or array of string]`
- `string`
- `array of string`
- `skipEnrichment: optional boolean`
Skip background enrichment for this contact creation. Defaults to false. Enrichment is a metered event, so when bulk-loading 50 or more records that do not require additional enrichment, we recommend `true`.
### Returns
- `ContactCreateResponse object { id, createdAt, fields, 4 more }`
- `id: string`
Unique identifier for the entity.
- `createdAt: string`
ISO 8601 timestamp of when the entity was created.
- `fields: map[object { value, valueType } ]`
Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug.
- `value: string or number or boolean or 3 more`
The field value, or null if unset.
- `string`
- `number`
- `boolean`
- `array of string`
- `Address object { city, country, latitude, 5 more }`
- `city: optional string`
City name.
- `country: optional string`
2-letter ISO 3166-1 alpha-2 country code.
- `latitude: optional number`
Latitude coordinate.
- `longitude: optional number`
Longitude coordinate.
- `postalCode: optional string`
Postal or ZIP code.
- `state: optional string`
State or province.
- `street: optional string`
Street address line 1.
- `street2: optional string`
Street address line 2.
- `FullName object { firstName, lastName }`
- `firstName: optional string`
The contact's first name.
- `lastName: optional string`
The contact's last name.
- `valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 12 more`
The data type of the field.
- `"ADDRESS"`
- `"CHECKBOX"`
- `"CURRENCY"`
- `"DATETIME"`
- `"EMAIL"`
- `"FULL_NAME"`
- `"MARKDOWN"`
- `"MULTI_SELECT"`
- `"NUMBER"`
- `"SINGLE_SELECT"`
- `"SOCIAL_HANDLE"`
- `"TELEPHONE"`
- `"TEXT"`
- `"URL"`
- `"HTML"`
- `httpLink: string`
URL to view the entity in the Lightfield web app, or null.
- `relationships: map[object { cardinality, objectType, values, directions } ]`
Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). A self-referential relationship keeps its merged values and includes optional directional values. List filters select the current record's role with `:asSource` or `:asDestination`, for example `?parent:asSource[contains]=account_id`.
- `cardinality: string`
Whether the relationship is `has_one` or `has_many`.
- `objectType: string`
The type of the related object (e.g. `account`, `contact`).
- `values: array of string`
IDs of the related entities.
- `directions: optional object { asDestination, asSource }`
Directional values for a self-referential relationship. List filters use the relationship key with `:asSource` or `:asDestination`; writes continue to use the bare key.
- `asDestination: object { cardinality, values }`
The current record is the destination (incoming) endpoint.
- `cardinality: "HAS_ONE" or "HAS_MANY"`
Whether this endpoint direction is `HAS_ONE` or `HAS_MANY`.
- `"HAS_ONE"`
- `"HAS_MANY"`
- `values: array of string`
IDs of the related entities in this direction.
- `asSource: object { cardinality, values }`
The current record is the source (outgoing) endpoint.
- `cardinality: "HAS_ONE" or "HAS_MANY"`
Whether this endpoint direction is `HAS_ONE` or `HAS_MANY`.
- `"HAS_ONE"`
- `"HAS_MANY"`
- `values: array of string`
IDs of the related entities in this direction.
- `updatedAt: string`
ISO 8601 timestamp of when the entity was last updated, or null.
- `externalId: optional string`
External identifier for the entity, or null if unset.
### Example
```http
curl https://api.lightfield.app/v1/contacts \
-H 'Content-Type: application/json' \
-H 'Lightfield-Version: 2026-03-01' \
-H "Authorization: Bearer $API_KEY" \
-d '{
"fields": {}
}'
```
#### Response
```json
{
"id": "id",
"createdAt": "createdAt",
"fields": {
"foo": {
"value": "string",
"valueType": "ADDRESS"
}
},
"httpLink": "httpLink",
"relationships": {
"foo": {
"cardinality": "cardinality",
"objectType": "objectType",
"values": [
"string"
],
"directions": {
"asDestination": {
"cardinality": "HAS_ONE",
"values": [
"string"
]
},
"asSource": {
"cardinality": "HAS_ONE",
"values": [
"string"
]
}
}
}
},
"updatedAt": "updatedAt",
"externalId": "externalId"
}
```