Guides
API reference
MCP server
ChangelogCreate a record
curl --request POST \
--url https://api-prod.heliyos.ai/v1/platform/base-schemas/{id}/records \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"deal_name": "Northwind Traders renewal",
"stage": "Negotiation",
"deal_value": 48000,
"close_date": "2026-12-15",
"assigned_to": [
{
"id": "66a0f1e2d3c4b5a697881111",
"firstName": "Dana",
"lastName": "Reyes",
"email": "dana@example.com"
}
],
"relationships": [
"66f1a8c3e4b0a1b2c3d4e5f6"
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
deal_name: 'Northwind Traders renewal',
stage: 'Negotiation',
deal_value: 48000,
close_date: '2026-12-15',
assigned_to: [
{
id: '66a0f1e2d3c4b5a697881111',
firstName: 'Dana',
lastName: 'Reyes',
email: 'dana@example.com'
}
],
relationships: ['66f1a8c3e4b0a1b2c3d4e5f6']
})
};
fetch('https://api-prod.heliyos.ai/v1/platform/base-schemas/{id}/records', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api-prod.heliyos.ai/v1/platform/base-schemas/{id}/records"
payload = {
"deal_name": "Northwind Traders renewal",
"stage": "Negotiation",
"deal_value": 48000,
"close_date": "2026-12-15",
"assigned_to": [
{
"id": "66a0f1e2d3c4b5a697881111",
"firstName": "Dana",
"lastName": "Reyes",
"email": "dana@example.com"
}
],
"relationships": ["66f1a8c3e4b0a1b2c3d4e5f6"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"meta": {
"message": "Object created successfully"
},
"data": {
"_id": "6721c3d5e6f7a8b9c0d1e2f3",
"baseSchemaId": "66a0f1e2d3c4b5a697880003",
"organizationId": "66a0f1e2d3c4b5a697887766",
"objectType": "deals",
"data": {
"deal_name": "Northwind Traders renewal",
"stage": "Negotiation",
"deal_value": 48000,
"close_date": "2026-12-15",
"assigned_to": [
{
"id": "66a0f1e2d3c4b5a697881111",
"firstName": "Dana",
"lastName": "Reyes",
"email": "dana@example.com"
}
]
},
"relationships": [
{
"_id": "6721c3d5e6f7a8b9c0d1e2f4",
"objectId": "66f1a8c3e4b0a1b2c3d4e5f6",
"schemaId": "66a0f1e2d3c4b5a697880001",
"objectType": "company"
}
],
"enrichmentDate": null,
"isAgentAssigned": false,
"aiColumnStatus": {},
"metadata": {
"created": {
"at": "2026-11-04T09:30:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
},
"updated": {
"at": "2026-11-04T09:30:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
}
}
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}Records
Create a record
Creates a record in an object. Send the field values at the top level of the body, keyed by the
object’s field keys (for example company_name, website, people_name, email, deal_name,
stage), and the ids of records to link in relationships.
Values by field type. Every type also accepts null and "".
| Field type | Value |
|---|---|
text, richText, phone, select | A string. A select value is not checked against the field’s options. |
email | An email address. |
url | A full URI, for example https://northwind.example. |
number, currency, rating | A number. |
checkbox | true or false. |
date, timestamp | An ISO 8601 date or date-time string. It is stored as sent. |
multiSelect | An array of strings. |
user | An array. The app stores team members as { "id", "firstName", "lastName", "email" }. |
image | An object. |
file | An array of { "fileName", "url" } objects, optionally with attachmentId, fileSize, mimeType, storageKey, uploadedAt. |
relationship | Any value. |
What is written.
- Fields the object marks required must be included.
- Only fields you may edit are written. Other keys, including keys that are not fields of the object,
are dropped without an error. Keys that start with
$or contain a dot are dropped too. - Field keys with a dot, such as
company.company_nameon people and deals, show a linked record’s value. Set them by linking that record inrelationships. - A field you leave out gets its configured default value, if it has one.
- Companies start with
account_statusandengagement_statusset tounknownunless you send them, and get alogobuilt fromwebsitewhen you send no logo. Companies and people start withenrichmentStatusNOT_ENRICHED. - A company whose
website, or a person whoseemail, exactly matches an existing record of the same object is refused with a 409. - Each linked record gets a link back to the new record.
Side effects. The create fires the company.created, people.created, deal.created (or custom
type) event, which can start workers that subscribe to it. A new deal sends the workspace’s deal
notification email when deal notifications are on. Companies, people and deals are sent to HubSpot
when the workspace syncs with it. A new company is enriched automatically when automatic enrichment
is on (Settings, Autopilot), which uses credits.
POST
/
v1
/
platform
/
base-schemas
/
{id}
/
records
Create a record
curl --request POST \
--url https://api-prod.heliyos.ai/v1/platform/base-schemas/{id}/records \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"deal_name": "Northwind Traders renewal",
"stage": "Negotiation",
"deal_value": 48000,
"close_date": "2026-12-15",
"assigned_to": [
{
"id": "66a0f1e2d3c4b5a697881111",
"firstName": "Dana",
"lastName": "Reyes",
"email": "dana@example.com"
}
],
"relationships": [
"66f1a8c3e4b0a1b2c3d4e5f6"
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
deal_name: 'Northwind Traders renewal',
stage: 'Negotiation',
deal_value: 48000,
close_date: '2026-12-15',
assigned_to: [
{
id: '66a0f1e2d3c4b5a697881111',
firstName: 'Dana',
lastName: 'Reyes',
email: 'dana@example.com'
}
],
relationships: ['66f1a8c3e4b0a1b2c3d4e5f6']
})
};
fetch('https://api-prod.heliyos.ai/v1/platform/base-schemas/{id}/records', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api-prod.heliyos.ai/v1/platform/base-schemas/{id}/records"
payload = {
"deal_name": "Northwind Traders renewal",
"stage": "Negotiation",
"deal_value": 48000,
"close_date": "2026-12-15",
"assigned_to": [
{
"id": "66a0f1e2d3c4b5a697881111",
"firstName": "Dana",
"lastName": "Reyes",
"email": "dana@example.com"
}
],
"relationships": ["66f1a8c3e4b0a1b2c3d4e5f6"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"meta": {
"message": "Object created successfully"
},
"data": {
"_id": "6721c3d5e6f7a8b9c0d1e2f3",
"baseSchemaId": "66a0f1e2d3c4b5a697880003",
"organizationId": "66a0f1e2d3c4b5a697887766",
"objectType": "deals",
"data": {
"deal_name": "Northwind Traders renewal",
"stage": "Negotiation",
"deal_value": 48000,
"close_date": "2026-12-15",
"assigned_to": [
{
"id": "66a0f1e2d3c4b5a697881111",
"firstName": "Dana",
"lastName": "Reyes",
"email": "dana@example.com"
}
]
},
"relationships": [
{
"_id": "6721c3d5e6f7a8b9c0d1e2f4",
"objectId": "66f1a8c3e4b0a1b2c3d4e5f6",
"schemaId": "66a0f1e2d3c4b5a697880001",
"objectType": "company"
}
],
"enrichmentDate": null,
"isAgentAssigned": false,
"aiColumnStatus": {},
"metadata": {
"created": {
"at": "2026-11-04T09:30:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
},
"updated": {
"at": "2026-11-04T09:30:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
}
}
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}In the Heliyos MCP server:
heliyos_records_create.Authorizations
A workspace API key, sent as Authorization: Bearer heliyos_.... Create one in Heliyos under Settings → API keys. A key acts as a workspace admin in the one workspace it was created in.
Path Parameters
The id of the object to create the record in.
Pattern:
^[0-9a-fA-F]{24}$Body
application/json
Field values keyed by the object's field keys, plus relationships.
Ids of records to link to the new record, for example a person's company. Each must be a record in this workspace; otherwise nothing is created and the call is a 404.
A 24-character hexadecimal id.
Pattern:
^[0-9a-fA-F]{24}$One property per field you set, named by the field's key (for example deal_name or stage). The value's shape depends on the field's type; see the table above.
Was this page helpful?