Skip to main content
POST
/
v1
/
companies
Create a company
curl --request POST \
  --url https://api.folk.app/v1/companies \
  --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": [
    "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.",
    "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": [
      "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"
          }
        ]
      }
    }
  }
}
Create a company in the workspace, optionally adding them to one or more groups. In the app, companies without groups will only be visible through the “Search” section.
Company names are unique across the workspace. If you try to create a company with a name that already exists, the existing company will be returned.

Authorizations

​
Authorization
string
header
required

API key for authentication

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
Pattern: ^\d{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:
["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 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": "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 company created 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": ["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"]