Skip to main content
POST
/
v1
/
groups
/
{groupId}
/
{entityType}
Create a deal
curl --request POST \
  --url https://api.folk.app/v1/groups/{groupId}/{entityType} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Project Alpha",
  "companies": [
    {
      "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c"
    }
  ],
  "people": [
    {
      "id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
    }
  ],
  "customFieldValues": {
    "Status": "Active",
    "Deal value": "42000",
    "Close date": "2021-01-01",
    "Assignee": [
      {
        "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6"
      },
      {
        "email": "jane@example.com"
      }
    ]
  }
}'
{
  "data": {
    "id": "obj_183ed5cc-3182-45de-84d1-d520f2604810",
    "name": "Project Alpha",
    "companies": [
      {
        "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c",
        "name": "Tech Corp"
      }
    ],
    "people": [
      {
        "id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2",
        "fullName": "John Doe"
      }
    ],
    "createdAt": "2021-01-01T00:00:00.000Z",
    "createdBy": {
      "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
      "fullName": "John Doe",
      "email": "john.doe@example.com"
    },
    "customFieldValues": {
      "Status": "Active",
      "Deal value": "42000",
      "Close date": "2021-01-01",
      "Assignee": [
        {
          "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6",
          "fullName": "Jane Doe",
          "email": "jane@example.com"
        }
      ]
    }
  }
}

Authorizations

​
Authorization
string
header
required

API key for authentication

Path Parameters

​
groupId
string
required

The ID of the group the deals belong to. Can be retrieved from the List groups endpoint.

Required string length: 40
​
entityType
string
required

The name of a deal custom field that can be retrieved from the List group custom fields endpoint.

Maximum length: 500

Body

application/json
​
name
string

The name of the deal.

Maximum length: 1000
Example:

"Project Alpha"

​
companies
object[]

The companies associated with the deal.

Maximum length: 20
Example:
[
  {
    "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c"
  }
]
​
people
object[]

The people associated with the deal.

Maximum length: 20
Example:
[
  {
    "id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2"
  }
]
​
customFieldValues
object

The custom field values associated with the deal. The format is the following:

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

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"]
  • 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"}]

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

Example:
{
  "Status": "Active",
  "Deal value": "42000",
  "Close date": "2021-01-01",
  "Assignee": [
    {
      "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6"
    },
    { "email": "jane@example.com" }
  ]
}

Response

The deal created in the workspace.

​
data
object
required

A deal in the workspace.

Example:
{
  "id": "obj_183ed5cc-3182-45de-84d1-d520f2604810",
  "name": "Project Alpha",
  "companies": [
    {
      "id": "com_92346499-30bf-4278-ae8e-4aa3ae2ace2c",
      "name": "Tech Corp"
    }
  ],
  "people": [
    {
      "id": "per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2",
      "fullName": "John Doe"
    }
  ],
  "createdAt": "2021-01-01T00:00:00.000Z",
  "createdBy": {
    "id": "usr_bc984b3f-0386-434d-82d7-a91eb6badd71",
    "fullName": "John Doe",
    "email": "john.doe@example.com"
  },
  "customFieldValues": {
    "Status": "Active",
    "Deal value": "42000",
    "Close date": "2021-01-01",
    "Assignee": [
      {
        "id": "usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6",
        "fullName": "Jane Doe",
        "email": "jane@example.com"
      }
    ]
  }
}
​
deprecations
string[]
Example:
["This field is deprecated"]