Skip to main content
PATCH
/
v1
/
companies
/
{companyId}
Update a company
curl --request PATCH \
  --url https://api.folk.app/v1/companies/{companyId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Tech Corp",
  "description": "A brief description of the company.",
  "groups": [
    {
      "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
    }
  ],
  "addresses": [
    "123 Main St, Springfield, USA",
    "456 Main St, Springfield, USA"
  ],
  "emails": [
    "john@example.com",
    "john@techcorp.com"
  ],
  "phones": [
    "+1234567890",
    "+0987654321"
  ],
  "urls": [
    "https://example.com",
    "https://example.com/about"
  ],
  "customFieldValues": {
    "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
      "Status": "Active",
      "Business type": [
        "B2B",
        "B2C"
      ],
      "Join date": "2021-01-01",
      "Relationships": [
        {
          "id": "per_ed110a47-5d09-43bf-b2e2-791d8231eb5f"
        },
        {
          "id": "com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03"
        }
      ]
    },
    "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
      "Custom Notes": "Important client, handle with care.",
      "ARR": 42000000,
      "Assignee": [
        {
          "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6"
        },
        {
          "email": "jane@example.com"
        }
      ]
    }
  }
}'
{
  "data": {
    "id": "com_183ed5cc-3182-45de-84d1-d520f2604810",
    "name": "Tech Corp",
    "description": "A leading technology company.",
    "groups": [
      {
        "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2",
        "name": "Engineering"
      }
    ],
    "addresses": [
      "123 Main St, Springfield, USA",
      "456 Main St, Springfield, USA"
    ],
    "emails": [
      "john@example.com",
      "john@techcorp.com"
    ],
    "phones": [
      "+1234567890",
      "+0987654321"
    ],
    "urls": [
      "https://example.com"
    ],
    "createdAt": "2021-01-01T00:00:00.000Z",
    "createdBy": {
      "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
      "fullName": "John Doe",
      "email": "john.doe@example.com"
    },
    "customFieldValues": {
      "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
        "Status": "Active",
        "Business type": [
          "B2B",
          "B2C"
        ],
        "Join date": "2021-01-01",
        "Relationships": [
          {
            "id": "per_ed110a47-5d09-43bf-b2e2-791d8231eb5f",
            "fullName": "Bob Smith",
            "entityType": "person"
          },
          {
            "id": "com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03",
            "fullName": "HR services",
            "entityType": "company"
          }
        ]
      },
      "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
        "Custom Notes": "Important client, handle with care.",
        "ARR": "42000000",
        "Assignee": [
          {
            "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6",
            "fullName": "Jane Doe",
            "email": "jane@example.com"
          }
        ]
      }
    }
  }
}
Update an existing company in the workspace, updating only the provided fields and leaving the rest of the company’s data unchanged.
Fields with a list of values (groups, addresses, emails, phones, urls) will replace the old values. This means that you must provide the entire list of values for that field, not just the values you want to add.
Company names are unique across the workspace. If you try to update a company with another company’s name, the request will fail.
When removing a company from a group, their custom field values for that group are also removed.

Authorizations

​
Authorization
string
header
required

API key for authentication

Path Parameters

​
companyId
string
required

The ID of the company to update.

Required string length: 40

Body

application/json
​
name
string

The name of the company.

Maximum length: 1000
Example:

"Tech Corp"

​
description
string

A short description of the company.

Maximum length: 5000
Example:

"A brief description of the company."

​
groups
object[]

The groups to add the company to. You must provide group ids.

Maximum length: 100
Example:
[
  {
    "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
  }
]
​
addresses
string[]

A list of addresses associated with the company. The first address in the list will be the company's primary address.

Maximum length: 20
Example:
[
  "123 Main St, Springfield, USA",
  "456 Main St, Springfield, USA"
]
​
emails
string[]

A list of email addresses associated with the company. The first email address in the list will be the company's primary email address.

Maximum length: 20
Example:
["john@example.com", "john@techcorp.com"]
​
phones
string[]

A list of phone numbers associated with the company. The first phone number in the list will be the company's primary phone number.

Maximum length: 20
Example:
["+1234567890", "+0987654321"]
​
urls
string[]

A list of URLs associated with the company. The first URL in the list will be the company's primary URL.

Maximum length: 20
Example:
[
  "https://example.com",
  "https://example.com/about"
]
​
customFieldValues
object

The custom field values associated with the company, grouped by group ids. The format is the following:

{
  "<groupId>": {
    "<customFieldName>": "<customFieldValue>"
  }
}

The group ids passed must also be provided in the groups field, otherwise a validation error will be thrown.

The format of the custom field value depends on the type of the custom field:

  • textField: string, eg: "Foo"
  • numericField: number or numeric string, eg: 42 or "42"
  • dateField: ISO 8601 string (YYYY-MM-DD), eg: "2021-01-01"
  • singleSelect: string (option label), eg: "Active"
  • multipleSelect: array of strings (option labels), eg: ["B2B", "B2C"]
  • contactField: array of objects with id property, eg: [{"id": "per_20228901-ce2b-418c-a267-671823107d8c"}]
  • userField: array of objects with either id (workspace user id) or email (workspace user email) property, eg: [{"id": "usr_a23373bb-5296-4c59-b2e8-8f121707d562"}, {"email": "jane@example.com"}]
  • magicField: string, eg: "foo"
  • objectField: array of objects with id property, eg: [{"id": "obj_2f62707c-52c0-421a-a11f-68e1ce9610f4"}]

Passing a null value or an empty array will unset the custom field value.

Example:
{
  "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
    "Status": "Active",
    "Business type": ["B2B", "B2C"],
    "Join date": "2021-01-01",
    "Relationships": [
      {
        "id": "per_ed110a47-5d09-43bf-b2e2-791d8231eb5f"
      },
      {
        "id": "com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03"
      }
    ]
  },
  "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
    "Custom Notes": "Important client, handle with care.",
    "ARR": 42000000,
    "Assignee": [
      {
        "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6"
      },
      { "email": "jane@example.com" }
    ]
  }
}

Response

The updated company in the workspace.

​
data
object
required

A company in the workspace.

Example:
{
  "id": "com_183ed5cc-3182-45de-84d1-d520f2604810",
  "name": "Tech Corp",
  "description": "A leading technology company.",
  "groups": [
    {
      "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2",
      "name": "Engineering"
    }
  ],
  "addresses": [
    "123 Main St, Springfield, USA",
    "456 Main St, Springfield, USA"
  ],
  "emails": ["john@example.com", "john@techcorp.com"],
  "phones": ["+1234567890", "+0987654321"],
  "urls": ["https://example.com"],
  "createdAt": "2021-01-01T00:00:00.000Z",
  "createdBy": {
    "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
    "fullName": "John Doe",
    "email": "john.doe@example.com"
  },
  "customFieldValues": {
    "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2": {
      "Status": "Active",
      "Business type": ["B2B", "B2C"],
      "Join date": "2021-01-01",
      "Relationships": [
        {
          "id": "per_ed110a47-5d09-43bf-b2e2-791d8231eb5f",
          "fullName": "Bob Smith",
          "entityType": "person"
        },
        {
          "id": "com_9a03f575-8a85-40b0-ba2e-16d8e29e3b03",
          "fullName": "HR services",
          "entityType": "company"
        }
      ]
    },
    "grp_acdf2ad9-6a66-4d32-8594-9694913ac717": {
      "Custom Notes": "Important client, handle with care.",
      "ARR": "42000000",
      "Assignee": [
        {
          "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6",
          "fullName": "Jane Doe",
          "email": "jane@example.com"
        }
      ]
    }
  }
}
​
deprecations
string[]
Example:
["This field is deprecated"]