API Documentation
Companies ¶
Companies ¶
Company resources are used to keep track of clients and manage their associated deals, budgets, contacts (people) and projects. More information about Companies can be found in our Help documentation: Adding Client Companies.
The /companies
endpoint allows you to create, update, delete, archive or unarchive (restore) Companies.
The following diagram shows Companies in our data hierarchy:
Since companies can have custom fields, please refer to the Working with custom fields guide for more details on how to work with them.
Supported attributes
-
name
(string) -
billing_name
(string) - full company name used on invoices -
vat
(string) - tax ID -
default_currency
(string) -
avatar_url
(string) -
custom_fields
(json) -
company_code
(string) - if it is not set through the API request when creating the company, it will be generated automatically -
domain
(string) -
description
(string) -
buyer_reference
(string) -
default_subsidiary_id
(integer) -
default_tax_rate_id
(integer) -
default_document_type_id
(integer) - defines the invoice template -
due_days
(integer) - related to payment terms -
tag_list
(array) -
contact
(json) - it is possible to add emails, phones, websites and addresses (city, state, ZIP code, country, billing address)
Supported filter params
Filter operations are supported on this endpoint for the following filters:
-
id
(integer) (array) -
company_id
(integer) (array) -
name
(string) -
company_code
(string) -
billing_name
(string) -
default_currency
(string) -
default_subsidiary_id
(string) (array) -
subsidiary_id
(integer) (array) -
default_tax_rate_id
(integer) (array) -
project_id
(integer) (array) -
vat
(string) -
status
(integer)- 1 (Active)
- 2 (Archived)
-
tags
(string) (array) -
created_at
(date) -
archived_at
(date) -
last_activity_at
(date) -
due_days
(integer) -
payment_terms
(integer) - equivalent to thedue_days
filter
GET /api/v2/companies
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": [
{
"id": "537",
"type": "companies",
"attributes": {
"name": "Client333",
"billing_name": null,
"vat": null,
"default_currency": null,
"created_at": "2025-07-24T06:04:41.953+02:00",
"last_activity_at": "2025-07-24T06:04:41.953+02:00",
"archived_at": null,
"avatar_url": null,
"invoice_email_recipients": {},
"custom_fields": null,
"company_code": "CLIE333",
"domain": null,
"projectless_budgets": false,
"leitweg_id": null,
"buyer_reference": null,
"peppol_id": null,
"default_subsidiary_id": null,
"default_tax_rate_id": null,
"default_document_type_id": null,
"description": null,
"due_days": null,
"tag_list": [],
"contact": {},
"sample_data": false,
"settings": {},
"external_id": null,
"external_sync": false
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "207"
}
},
"default_subsidiary": {
"meta": {
"included": false
}
},
"default_tax_rate": {
"meta": {
"included": false
}
},
"custom_field_people": {
"meta": {
"included": false
}
},
"custom_field_attachments": {
"meta": {
"included": false
}
}
}
},
{
"id": "536",
"type": "companies",
"attributes": {
"name": "Organization207",
"billing_name": null,
"vat": null,
"default_currency": null,
"created_at": "2025-07-24T06:04:41.942+02:00",
"last_activity_at": "2025-07-24T06:04:41.942+02:00",
"archived_at": null,
"avatar_url": null,
"invoice_email_recipients": {},
"custom_fields": null,
"company_code": "ORGA",
"domain": null,
"projectless_budgets": false,
"leitweg_id": null,
"buyer_reference": null,
"peppol_id": null,
"default_subsidiary_id": null,
"default_tax_rate_id": null,
"default_document_type_id": null,
"description": null,
"due_days": null,
"tag_list": [],
"contact": {},
"sample_data": false,
"settings": {},
"external_id": null,
"external_sync": false
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "207"
}
},
"default_subsidiary": {
"meta": {
"included": false
}
},
"default_tax_rate": {
"meta": {
"included": false
}
},
"custom_field_people": {
"meta": {
"included": false
}
},
"custom_field_attachments": {
"meta": {
"included": false
}
}
}
}
],
"links": {
"first": "http://api-test.productive.io/api/v2/companies?page%5Bnumber%5D=1&page%5Bsize%5D=30",
"last": "http://api-test.productive.io/api/v2/companies?page%5Bnumber%5D=1&page%5Bsize%5D=30"
},
"meta": {
"current_page": 1,
"total_pages": 1,
"total_count": 2,
"page_size": 30,
"max_page_size": 200
}
}
Get companiesGET/api/v2/companies
GET /api/v2/companies/539
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": {
"id": "539",
"type": "companies",
"attributes": {
"name": "Client334",
"billing_name": null,
"vat": null,
"default_currency": null,
"created_at": "2025-07-24T06:04:42.021+02:00",
"last_activity_at": "2025-07-24T06:04:42.021+02:00",
"archived_at": null,
"avatar_url": null,
"invoice_email_recipients": {},
"custom_fields": null,
"company_code": "CLIE334",
"domain": null,
"projectless_budgets": false,
"leitweg_id": null,
"buyer_reference": null,
"peppol_id": null,
"default_subsidiary_id": null,
"default_tax_rate_id": null,
"default_document_type_id": null,
"description": null,
"due_days": null,
"tag_list": [],
"contact": {},
"sample_data": false,
"settings": {},
"external_id": null,
"external_sync": false
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "208"
}
},
"default_subsidiary": {
"meta": {
"included": false
}
},
"default_tax_rate": {
"meta": {
"included": false
}
},
"custom_field_people": {
"meta": {
"included": false
}
},
"custom_field_attachments": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}
POST /api/v2/companies
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "companies",
"attributes": {
"name": "ACME Comp.",
"avatar_url": "https://example.com/logo.png",
"description": "ACME company",
"due_days": 15,
"default_currency": "EUR",
"company_code": "COMP",
"billing_name": "ACME Company Ltd.",
"vat": "123456789",
"domain": "acme.com",
"tag_list": [
"partner",
"priority"
],
"buyer_reference": "BUYER123",
"contact": {
"phones": [
{
"name": "Contact phone",
"phone": "(555) 123-4567"
}
],
"emails": [
{
"name": "Email",
"email": "contact@exmaple.com"
}
],
"websites": [
{
"name": "Official website",
"website": "example-website.com"
}
],
"addresses": [
{
"name": "Headquarters",
"billing_address": "Main Street",
"city": "City",
"state": "State",
"zipcode": "11111",
"country": "Country"
}
]
}
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": {
"id": "542",
"type": "companies",
"attributes": {
"name": "ACME Comp.",
"billing_name": "ACME Company Ltd.",
"vat": "123456789",
"default_currency": "EUR",
"created_at": "2025-07-24T06:04:42.101+02:00",
"last_activity_at": "2025-07-24T06:04:42.101+02:00",
"archived_at": null,
"avatar_url": "https://example.com/logo.png",
"invoice_email_recipients": {},
"custom_fields": null,
"company_code": "COMP",
"domain": "acme.com",
"projectless_budgets": false,
"leitweg_id": null,
"buyer_reference": "BUYER123",
"peppol_id": null,
"default_subsidiary_id": null,
"default_tax_rate_id": null,
"default_document_type_id": null,
"description": "ACME company",
"due_days": 15,
"tag_list": [
"partner",
"priority"
],
"contact": {
"phones": [
{
"name": "Contact phone",
"phone": "(555) 123-4567",
"contact_datum_id": 37
}
],
"emails": [
{
"name": "Email",
"email": "contact@exmaple.com",
"contact_datum_id": 38
}
],
"websites": [
{
"name": "Official website",
"website": "example-website.com",
"contact_datum_id": 39
}
],
"addresses": [
{
"name": "Headquarters",
"billing_address": "Main Street",
"city": "City",
"state": "State",
"zipcode": "11111",
"country": "Country",
"contact_datum_id": 40
}
]
},
"sample_data": false,
"settings": null,
"external_id": null,
"external_sync": false
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "209"
}
},
"default_subsidiary": {
"meta": {
"included": false
}
},
"default_tax_rate": {
"meta": {
"included": false
}
},
"custom_field_people": {
"meta": {
"included": false
}
},
"custom_field_attachments": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}
POST /api/v2/companies
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "companies",
"attributes": {
"name": ""
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"errors": [
{
"status": "422",
"code": "invalid_attribute",
"title": "Invalid Attribute",
"detail": "can't be blank",
"source": {
"pointer": "data/attributes/name"
}
}
]
}
PATCH /api/v2/companies/546
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "companies",
"attributes": {
"name": "new name",
"domain": "new.domain",
"tag_list": [
"design",
"IT"
]
},
"relationships": {
"subscribers": {
"data": [
{
"type": "people",
"id": "800"
},
{
"type": "people",
"id": "801"
}
]
}
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": {
"id": "546",
"type": "companies",
"attributes": {
"name": "new name",
"billing_name": null,
"vat": null,
"default_currency": null,
"created_at": "2025-07-24T06:04:42.295+02:00",
"last_activity_at": "2025-07-24T06:04:42.295+02:00",
"archived_at": null,
"avatar_url": null,
"invoice_email_recipients": {},
"custom_fields": null,
"company_code": "CLIE337",
"domain": "new.domain",
"projectless_budgets": false,
"leitweg_id": null,
"buyer_reference": null,
"peppol_id": null,
"default_subsidiary_id": null,
"default_tax_rate_id": null,
"default_document_type_id": null,
"description": null,
"due_days": null,
"tag_list": [
"design",
"IT"
],
"contact": {},
"sample_data": false,
"settings": {},
"external_id": null,
"external_sync": false
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "211"
}
},
"default_subsidiary": {
"meta": {
"included": false
}
},
"default_tax_rate": {
"meta": {
"included": false
}
},
"custom_field_people": {
"meta": {
"included": false
}
},
"custom_field_attachments": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}
PATCH /api/v2/companies/548
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "companies",
"attributes": {
"name": ""
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"errors": [
{
"status": "422",
"code": "invalid_attribute",
"title": "Invalid Attribute",
"detail": "can't be blank",
"source": {
"pointer": "data/attributes/name"
}
}
]
}
PATCH /api/v2/companies/550
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "companies",
"attributes": {
"domain": "gmail.com"
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"errors": [
{
"status": "422",
"code": "invalid_attribute",
"title": "Invalid Attribute",
"detail": "public domains are not allowed",
"source": {
"pointer": "data/attributes/domain"
}
}
]
}
PATCH /api/v2/companies/552
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "companies",
"attributes": {
"domain": "productive.io"
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"errors": [
{
"status": "422",
"code": "invalid_attribute",
"title": "Invalid Attribute",
"detail": "domain already taken",
"source": {
"pointer": "data/attributes/domain"
}
}
]
}
PATCH /api/v2/companies/555
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "companies",
"attributes": {
"domain": ""
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"errors": [
{
"status": "422",
"code": "invalid_attribute",
"title": "Invalid Attribute",
"detail": "domain can't be empty string",
"source": {
"pointer": "data/attributes/domain"
}
}
]
}
PATCH /api/v2/companies/557
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "companies",
"attributes": {
"domain": null
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": {
"id": "557",
"type": "companies",
"attributes": {
"name": "Client343",
"billing_name": null,
"vat": null,
"default_currency": null,
"created_at": "2025-07-24T06:04:42.619+02:00",
"last_activity_at": "2025-07-24T06:04:42.619+02:00",
"archived_at": null,
"avatar_url": null,
"invoice_email_recipients": {},
"custom_fields": null,
"company_code": "CLIE343",
"domain": null,
"projectless_budgets": false,
"leitweg_id": null,
"buyer_reference": null,
"peppol_id": null,
"default_subsidiary_id": null,
"default_tax_rate_id": null,
"default_document_type_id": null,
"description": null,
"due_days": null,
"tag_list": [],
"contact": {},
"sample_data": false,
"settings": {},
"external_id": null,
"external_sync": false
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "216"
}
},
"default_subsidiary": {
"meta": {
"included": false
}
},
"default_tax_rate": {
"meta": {
"included": false
}
},
"custom_field_people": {
"meta": {
"included": false
}
},
"custom_field_attachments": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}
PATCH /api/v2/companies/559
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "companies",
"attributes": {
"domain": "invalid@format"
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"errors": [
{
"status": "422",
"code": "invalid_attribute",
"title": "Invalid Attribute",
"detail": "domain format not valid",
"source": {
"pointer": "data/attributes/domain"
}
}
]
}
PATCH /api/v2/companies/561
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "companies",
"attributes": {
"name": "Hubspot deal"
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": {
"id": "561",
"type": "companies",
"attributes": {
"name": "Hubspot deal",
"billing_name": null,
"vat": null,
"default_currency": null,
"created_at": "2025-07-24T06:04:42.726+02:00",
"last_activity_at": "2025-07-24T06:04:42.726+02:00",
"archived_at": null,
"avatar_url": null,
"invoice_email_recipients": {},
"custom_fields": null,
"company_code": "CLIE345",
"domain": null,
"projectless_budgets": false,
"leitweg_id": null,
"buyer_reference": null,
"peppol_id": null,
"default_subsidiary_id": null,
"default_tax_rate_id": null,
"default_document_type_id": null,
"description": null,
"due_days": null,
"tag_list": [],
"contact": {},
"sample_data": false,
"settings": {},
"external_id": "123",
"external_sync": false
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "218"
}
},
"default_subsidiary": {
"meta": {
"included": false
}
},
"default_tax_rate": {
"meta": {
"included": false
}
},
"custom_field_people": {
"meta": {
"included": false
}
},
"custom_field_attachments": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}
PATCH /api/v2/companies/563
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
"data": {
"type": "companies",
"attributes": {
"description": "We are syncing! What are you singing about?"
}
}
}
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": {
"id": "563",
"type": "companies",
"attributes": {
"name": "Client346",
"billing_name": null,
"vat": null,
"default_currency": null,
"created_at": "2025-07-24T06:04:42.789+02:00",
"last_activity_at": "2025-07-24T06:04:42.789+02:00",
"archived_at": null,
"avatar_url": null,
"invoice_email_recipients": {},
"custom_fields": null,
"company_code": "CLIE346",
"domain": null,
"projectless_budgets": false,
"leitweg_id": null,
"buyer_reference": null,
"peppol_id": null,
"default_subsidiary_id": null,
"default_tax_rate_id": null,
"default_document_type_id": null,
"description": "We are syncing! What are you singing about?",
"due_days": null,
"tag_list": [],
"contact": {},
"sample_data": false,
"settings": {},
"external_id": "123",
"external_sync": true
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "219"
}
},
"default_subsidiary": {
"meta": {
"included": false
}
},
"default_tax_rate": {
"meta": {
"included": false
}
},
"custom_field_people": {
"meta": {
"included": false
}
},
"custom_field_attachments": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}
PATCH /api/v2/companies/565/archive
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": {
"id": "565",
"type": "companies",
"attributes": {
"name": "Client347",
"billing_name": null,
"vat": null,
"default_currency": null,
"created_at": "2025-07-24T06:04:42.863+02:00",
"last_activity_at": "2025-07-24T06:04:42.863+02:00",
"archived_at": "2025-07-24T06:04:42.000+02:00",
"avatar_url": null,
"invoice_email_recipients": {},
"custom_fields": null,
"company_code": "CLIE347",
"domain": null,
"projectless_budgets": false,
"leitweg_id": null,
"buyer_reference": null,
"peppol_id": null,
"default_subsidiary_id": null,
"default_tax_rate_id": null,
"default_document_type_id": null,
"description": null,
"due_days": null,
"tag_list": [],
"contact": {},
"sample_data": false,
"settings": {},
"external_id": null,
"external_sync": false
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "220"
}
},
"default_subsidiary": {
"meta": {
"included": false
}
},
"default_tax_rate": {
"meta": {
"included": false
}
},
"custom_field_people": {
"meta": {
"included": false
}
},
"custom_field_attachments": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}
Archives a companyPATCH/api/v2/companies/{id}/archive
- id
number
(required) Example: 1company id
PATCH /api/v2/companies/571/restore
Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
"data": {
"id": "571",
"type": "companies",
"attributes": {
"name": "Client350",
"billing_name": null,
"vat": null,
"default_currency": null,
"created_at": "2025-07-24T06:04:42.990+02:00",
"last_activity_at": "2025-07-24T06:04:42.990+02:00",
"archived_at": null,
"avatar_url": null,
"invoice_email_recipients": {},
"custom_fields": null,
"company_code": "CLIE350",
"domain": null,
"projectless_budgets": false,
"leitweg_id": null,
"buyer_reference": null,
"peppol_id": null,
"default_subsidiary_id": null,
"default_tax_rate_id": null,
"default_document_type_id": null,
"description": null,
"due_days": null,
"tag_list": [],
"contact": {},
"sample_data": false,
"settings": {},
"external_id": null,
"external_sync": false
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "223"
}
},
"default_subsidiary": {
"meta": {
"included": false
}
},
"default_tax_rate": {
"meta": {
"included": false
}
},
"custom_field_people": {
"meta": {
"included": false
}
},
"custom_field_attachments": {
"meta": {
"included": false
}
}
}
},
"meta": {}
}
Restores a companyPATCH/api/v2/companies/{id}/restore
- id
number
(required) Example: 1company id
Generated by aglio on 24 Jul 2025