Create a company

Create a new company in the workspace.

POST /v1/companies

Create a company

cURL

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": [
    "[e-mail]",
    "[e-mail]"
  ],
  "phones": [
    "[phone]",
    "+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": "[e-mail]"
        }
      ]
    }
  }
}
'

200

{
  "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": [
      "[e-mail]",
      "[e-mail]"
    ],
    "phones": [
      "[phone]",
      "+0987654321"
    ],
    "urls": [
      "https://example.com"
    ],
    "createdAt": "2021-01-01T00:00:00.000Z",
    "createdBy": {
      "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
      "fullName": "John Doe",
      "email": "[e-mail]"
    },
    "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": "[e-mail]"
          }
        ]
      }
    }
  }
}

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 · number string

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 · string number

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

Show child attributes

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:

["[e-mail]", "[e-mail]"]

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:

["[phone]", "+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": "[e-mail]"}]
• 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.

Show child attributes

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": "[e-mail]" }
    ]
  }
}

Response

200

application/json

The company created in the workspace.

data · object · required

A company in the workspace.

Show child attributes

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": ["[e-mail]", "[e-mail]"],
  "phones": ["[phone]", "+0987654321"],
  "urls": ["https://example.com"],
  "createdAt": "2021-01-01T00:00:00.000Z",
  "createdBy": {
    "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
    "fullName": "John Doe",
    "email": "[e-mail]"
  },
  "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": "[e-mail]"
        }
      ]
    }
  }
}

deprecations · string[]

Example:

["This field is deprecated"]