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.",
  "fundingRaised": 100000,
  "lastFundingDate": "1990-01-01",
  "industry": "Technology",
  "foundationYear": "1990",
  "employeeRange": "51-200",
  "groups": [
    {
      "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
    }
  ],
  "addresses": [
    "123 Main St, Springfield, USA",
    "456 Main St, Springfield, USA"
  ],
  "emails": [
    "[email protected]",
    "[email protected]"
  ],
  "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": "[email protected]"
        }
      ]
    }
  }
}
'
{
  "data": {
    "id": "com_183ed5cc-3182-45de-84d1-d520f2604810",
    "name": "Tech Corp",
    "description": "A leading technology company.",
    "fundingRaised": "5000000",
    "lastFundingDate": "1990-01-01",
    "industry": "Technology",
    "foundationYear": "1990",
    "employeeRange": "51-200",
    "groups": [
      {
        "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2",
        "name": "Engineering"
      }
    ],
    "addresses": [
      "123 Main St, Springfield, USA",
      "456 Main St, Springfield, USA"
    ],
    "emails": [
      "[email protected]",
      "[email protected]"
    ],
    "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": "[email protected]"
    },
    "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": "[email protected]"
          }
        ]
      }
    }
  }
}
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 string length: 1000
Example:

"Tech Corp"

​
description
string

A short description of the company.

Maximum string length: 5000
Example:

"A brief description of the company."

​
fundingRaised

The amount of funding raised by the company in USD, as a number.

Example:

100000

​
lastFundingDate
string<date> | null

The date of the last funding round for the company, in YYYY-MM-DD format.

Required string length: 10
Example:

"1990-01-01"

​
industry
string | null

The industry the company operates in.

Maximum string length: 1000
Example:

"Technology"

​
foundationYear

The foundation year of the company, in YYYY format as string.

Required string length: 4
Example:

"1990"

​
employeeRange
enum<string> | null

The employee range of the company.

Available options:
1-10,
11-50,
51-200,
201-500,
501-1000,
1001-5000,
5001-10000,
10000+
Example:

"51-200"

​
groups
object[]

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

Maximum array 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 array length: 20
Maximum string length: 500
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 array length: 20
Maximum string length: 254
Example:
["[email protected]", "[email protected]"]
​
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 array length: 20
Maximum string length: 30
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 array length: 20
Maximum string length: 2048
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": "[email protected]"}]
  • 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": "[email protected]" }
    ]
  }
}

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.",
  "fundingRaised": "5000000",
  "lastFundingDate": "1990-01-01",
  "industry": "Technology",
  "foundationYear": "1990",
  "employeeRange": "51-200",
  "groups": [
    {
      "id": "grp_5fa60242-0756-4e31-8cca-30c2c5ff1ac2",
      "name": "Engineering"
    }
  ],
  "addresses": [
    "123 Main St, Springfield, USA",
    "456 Main St, Springfield, USA"
  ],
  "emails": ["[email protected]", "[email protected]"],
  "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": "[email protected]"
  },
  "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": "[email protected]"
        }
      ]
    }
  }
}
​
deprecations
string[]
Example:
["This field is deprecated"]