Create or update a company
curl --request POST \
--url https://app.gaintrace.com/api/v1/companies \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"externalId": "<string>",
"domain": "<string>",
"industry": "<string>",
"plan": "<string>",
"segment": "<string>",
"region": "<string>",
"location": "<string>",
"lifecycleStage": "<string>",
"ownerEmail": "<string>",
"employeeCount": 1,
"arr": 1,
"mrr": 1,
"currency": "<string>",
"contractStartDate": "2023-11-07T05:31:56Z",
"contractEndDate": "2023-11-07T05:31:56Z",
"autoRenew": true
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
externalId: '<string>',
domain: '<string>',
industry: '<string>',
plan: '<string>',
segment: '<string>',
region: '<string>',
location: '<string>',
lifecycleStage: '<string>',
ownerEmail: '<string>',
employeeCount: 1,
arr: 1,
mrr: 1,
currency: '<string>',
contractStartDate: '2023-11-07T05:31:56Z',
contractEndDate: '2023-11-07T05:31:56Z',
autoRenew: true
})
};
fetch('https://app.gaintrace.com/api/v1/companies', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://app.gaintrace.com/api/v1/companies"
payload = {
"name": "<string>",
"externalId": "<string>",
"domain": "<string>",
"industry": "<string>",
"plan": "<string>",
"segment": "<string>",
"region": "<string>",
"location": "<string>",
"lifecycleStage": "<string>",
"ownerEmail": "<string>",
"employeeCount": 1,
"arr": 1,
"mrr": 1,
"currency": "<string>",
"contractStartDate": "2023-11-07T05:31:56Z",
"contractEndDate": "2023-11-07T05:31:56Z",
"autoRenew": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"externalId": "<string>",
"name": "<string>",
"domain": "<string>",
"industry": "<string>",
"employeeCount": 123,
"plan": "<string>",
"segment": "<string>",
"region": "<string>",
"location": "<string>",
"lifecycleStage": "<string>",
"ownerEmail": "<string>",
"arr": 123,
"mrr": 123,
"currency": "<string>",
"contractStartDate": "2023-11-07T05:31:56Z",
"contractEndDate": "2023-11-07T05:31:56Z",
"autoRenew": true,
"healthScore": 123,
"healthStatus": "healthy",
"contactCount": 123,
"dealCount": 123,
"isPhantom": true,
"lastActivityAt": "2023-11-07T05:31:56Z",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
}{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"externalId": "<string>",
"name": "<string>",
"domain": "<string>",
"industry": "<string>",
"employeeCount": 123,
"plan": "<string>",
"segment": "<string>",
"region": "<string>",
"location": "<string>",
"lifecycleStage": "<string>",
"ownerEmail": "<string>",
"arr": 123,
"mrr": 123,
"currency": "<string>",
"contractStartDate": "2023-11-07T05:31:56Z",
"contractEndDate": "2023-11-07T05:31:56Z",
"autoRenew": true,
"healthScore": 123,
"healthStatus": "healthy",
"contactCount": 123,
"dealCount": 123,
"isPhantom": true,
"lastActivityAt": "2023-11-07T05:31:56Z",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "bad_request",
"message": "Invalid JSON body",
"doc_url": "https://docs.gaintrace.com/errors#bad_request"
}
}{
"error": {
"code": "unauthorized",
"message": "Missing Authorization header",
"doc_url": "https://docs.gaintrace.com/errors#unauthorized"
}
}{
"error": {
"code": "forbidden",
"message": "Insufficient scope: write:companies required",
"doc_url": "https://docs.gaintrace.com/errors#forbidden"
}
}{
"error": {
"code": "unprocessable_entity",
"message": "Request validation failed. name: name is required",
"doc_url": "https://docs.gaintrace.com/errors#unprocessable_entity"
}
}{
"error": {
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded. Maximum 120 requests per minute per API key.",
"doc_url": "https://docs.gaintrace.com/errors#rate_limit_exceeded"
}
}{
"error": {
"code": "internal_server_error",
"message": "Something went wrong. Try again in a moment.",
"doc_url": "https://docs.gaintrace.com/errors#internal_server_error"
}
}{
"error": {
"code": "service_unavailable",
"message": "We had trouble reaching the database. Try again in a moment.",
"doc_url": "https://docs.gaintrace.com/errors#service_unavailable"
}
}{
"error": {
"code": "gateway_timeout",
"message": "The request timed out. Try again in a moment.",
"doc_url": "https://docs.gaintrace.com/errors#gateway_timeout"
}
}Companies
Create or update a company
Creates a company, or updates the existing one with the same externalId (upsert).
Scope: write:companies
POST
/
companies
Create or update a company
curl --request POST \
--url https://app.gaintrace.com/api/v1/companies \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"externalId": "<string>",
"domain": "<string>",
"industry": "<string>",
"plan": "<string>",
"segment": "<string>",
"region": "<string>",
"location": "<string>",
"lifecycleStage": "<string>",
"ownerEmail": "<string>",
"employeeCount": 1,
"arr": 1,
"mrr": 1,
"currency": "<string>",
"contractStartDate": "2023-11-07T05:31:56Z",
"contractEndDate": "2023-11-07T05:31:56Z",
"autoRenew": true
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
externalId: '<string>',
domain: '<string>',
industry: '<string>',
plan: '<string>',
segment: '<string>',
region: '<string>',
location: '<string>',
lifecycleStage: '<string>',
ownerEmail: '<string>',
employeeCount: 1,
arr: 1,
mrr: 1,
currency: '<string>',
contractStartDate: '2023-11-07T05:31:56Z',
contractEndDate: '2023-11-07T05:31:56Z',
autoRenew: true
})
};
fetch('https://app.gaintrace.com/api/v1/companies', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://app.gaintrace.com/api/v1/companies"
payload = {
"name": "<string>",
"externalId": "<string>",
"domain": "<string>",
"industry": "<string>",
"plan": "<string>",
"segment": "<string>",
"region": "<string>",
"location": "<string>",
"lifecycleStage": "<string>",
"ownerEmail": "<string>",
"employeeCount": 1,
"arr": 1,
"mrr": 1,
"currency": "<string>",
"contractStartDate": "2023-11-07T05:31:56Z",
"contractEndDate": "2023-11-07T05:31:56Z",
"autoRenew": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"externalId": "<string>",
"name": "<string>",
"domain": "<string>",
"industry": "<string>",
"employeeCount": 123,
"plan": "<string>",
"segment": "<string>",
"region": "<string>",
"location": "<string>",
"lifecycleStage": "<string>",
"ownerEmail": "<string>",
"arr": 123,
"mrr": 123,
"currency": "<string>",
"contractStartDate": "2023-11-07T05:31:56Z",
"contractEndDate": "2023-11-07T05:31:56Z",
"autoRenew": true,
"healthScore": 123,
"healthStatus": "healthy",
"contactCount": 123,
"dealCount": 123,
"isPhantom": true,
"lastActivityAt": "2023-11-07T05:31:56Z",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
}{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"externalId": "<string>",
"name": "<string>",
"domain": "<string>",
"industry": "<string>",
"employeeCount": 123,
"plan": "<string>",
"segment": "<string>",
"region": "<string>",
"location": "<string>",
"lifecycleStage": "<string>",
"ownerEmail": "<string>",
"arr": 123,
"mrr": 123,
"currency": "<string>",
"contractStartDate": "2023-11-07T05:31:56Z",
"contractEndDate": "2023-11-07T05:31:56Z",
"autoRenew": true,
"healthScore": 123,
"healthStatus": "healthy",
"contactCount": 123,
"dealCount": 123,
"isPhantom": true,
"lastActivityAt": "2023-11-07T05:31:56Z",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "bad_request",
"message": "Invalid JSON body",
"doc_url": "https://docs.gaintrace.com/errors#bad_request"
}
}{
"error": {
"code": "unauthorized",
"message": "Missing Authorization header",
"doc_url": "https://docs.gaintrace.com/errors#unauthorized"
}
}{
"error": {
"code": "forbidden",
"message": "Insufficient scope: write:companies required",
"doc_url": "https://docs.gaintrace.com/errors#forbidden"
}
}{
"error": {
"code": "unprocessable_entity",
"message": "Request validation failed. name: name is required",
"doc_url": "https://docs.gaintrace.com/errors#unprocessable_entity"
}
}{
"error": {
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded. Maximum 120 requests per minute per API key.",
"doc_url": "https://docs.gaintrace.com/errors#rate_limit_exceeded"
}
}{
"error": {
"code": "internal_server_error",
"message": "Something went wrong. Try again in a moment.",
"doc_url": "https://docs.gaintrace.com/errors#internal_server_error"
}
}{
"error": {
"code": "service_unavailable",
"message": "We had trouble reaching the database. Try again in a moment.",
"doc_url": "https://docs.gaintrace.com/errors#service_unavailable"
}
}{
"error": {
"code": "gateway_timeout",
"message": "The request timed out. Try again in a moment.",
"doc_url": "https://docs.gaintrace.com/errors#gateway_timeout"
}
}Authorizations
Bearer API key. Secret server keys start with gt_live_; client-safe browser keys start with gt_pub_ (write-only, origin-pinned). Create and scope keys in Settings → API Keys.
Body
application/json
Create or update a company. Upserts on externalId (defaults to a slug of name).
Required string length:
1 - 255Upsert key. Defaults to a slug of the name.
Maximum string length:
100Maximum string length:
255Maximum string length:
100Maximum string length:
50Maximum string length:
50Maximum string length:
100Maximum string length:
255Maximum string length:
30Maximum string length:
255Required range:
x >= 0Integer minor units.
Required range:
x >= 0Integer minor units.
Required range:
x >= 0ISO 4217 code or null.
Maximum string length:
3Pattern:
^[A-Z]{3}$Response
Existing company updated.
A canonical company record. Health, counts, and timestamps are read-only.
Show child attributes
Show child attributes
Last modified on July 7, 2026
Was this page helpful?
⌘I