Skip to main content
PATCH
/
v1
/
groups
/
{groupId}
/
{entityType}
/
{dealId}
Update a deal
curl --request PATCH \
  --url https://api.folk.app/v1/groups/{groupId}/{entityType}/{dealId} \
  --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"
        }
      ]
    }
  }
}
Update an existing deal in the workspace, updating only the provided fields and leaving the rest of the deal’s data unchanged.
Fields with a list of values (people, companies) 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.

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
​
dealId
string
required

The ID of the deal to update.

Required string length: 40

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 updated deal 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"]