Custom objects

A custom object is a record of an object type defined inside a group: Deals, Projects, Job Applications, Partnerships, or anything else your workflow needs. Objects link the people and companies of the group to what you are working on with them. A job application is usually about one candidate, so it links a person. A partnership is between organizations, so it links companies. A deal often links both: the company buying and the people negotiating.

Deals are custom objects

A deal is an object whose object type is named Deals. It is not a separate resource: deals are read and written with the custom object endpoints, like any other object type, with Deals as the objectType path parameter.

curl -X GET "https://api.folk.app/v1/groups/grp_bc984b3f-0386-434d-82d7-a91eb6badd71/Deals" \
  -H "Authorization: Bearer YOUR_API_KEY"

Reading job applications is the same request, with another objectType:

curl -X GET "https://api.folk.app/v1/groups/grp_bc984b3f-0386-434d-82d7-a91eb6badd71/Job%20Applications" \
  -H "Authorization: Bearer YOUR_API_KEY"

Everything on this page applies equally to deals and to every other object type.

Object types

Object types are defined per group, like custom fields are. A “Hiring” group might define a “Job Applications” object type, while a “Partners” group defines “Partnerships”. The two are independent, even inside the same workspace.

An object type is not tied to people or to companies: every object, whatever its type, can link both. Linking only people, only companies, or both is a choice of your workflow, not of the object type.

Object types are group specific. Two groups can each define an object type with the same name, and they will not share their custom fields.

Every object endpoint takes the object type in its path, after the group: /v1/groups/{groupId}/{objectType}. The sections below explain how to find, manage and use that objectType.

Find the object types of a group

The objectType path parameter is the name of the object type, exactly as it appears in the folk app. The match is case-sensitive: deals is not Deals.

To list the object types available in a group, call List group custom fields with person or company as the entity type: object types are shared by people and companies, so both return them. Every field returned with a type of objectField is an object type, and its name is the value to pass as objectType.

curl -X GET "https://api.folk.app/v1/groups/grp_bc984b3f-0386-434d-82d7-a91eb6badd71/custom-fields/person" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "items": [
      { "name": "Deals", "type": "objectField" },
      { "name": "Job Applications", "type": "objectField" },
      { "name": "Lifecycle stage", "type": "singleSelect" }
    ],
    "pagination": {}
  }
}

In the response above, both Deals and Job Applications can be used as objectType. A name with spaces or other reserved characters must be URL-encoded in the path:

GET /v1/groups/grp_bc984b3f-0386-434d-82d7-a91eb6badd71/Job%20Applications

Unknown object types

When the objectType in the path of an object endpoint does not exist in the group, the request returns a 404 Not Found response, whose message lists the object types of the group. For example, GET /v1/groups/grp_bc984b3f-0386-434d-82d7-a91eb6badd71/deals returns:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Object type \"deals\" not found in group \"grp_bc984b3f-0386-434d-82d7-a91eb6badd71\". Available object types are: \"Deals\", \"Job Applications\"."
  }
}

• Single routes (list, get, create, update, delete) return that 404. If the API key has no access to the group, they return 403 Forbidden instead, whether the object type exists or not.
• Batch routes (create, update and delete in batch) fail the whole request with that 404, before any record is processed. If the API key has no access to the group, the request succeeds, and every record fails with a FORBIDDEN error.

Manage object types

Object types are managed with the group custom field endpoints:

• Create an object type: call Create a group custom field with person or company as the entity type and objectField as the type. Both give the same result: the new object type is shared by people and companies, and is listed with both entity types. It is named after the field, and can be used as objectType right away.
• Rename an object type: call Update a group custom field on that field. The objectType of its objects changes with it.
• Manage the custom fields of an object type: call List group custom fields or Create a group custom field with the name of the object type as the entity type, for instance Deals.

Object fields

All the objects of a type have the same fields: two deals of a group can have different values, but not different fields.

Native fields

Every object, whatever its type, has the same native fields:

• name: The name of the object.
• people: A list of people associated with the object.
• companies: A list of companies associated with the object.
• createdAt: The date and time the object was created.
• createdBy: The user who created the object.

Custom object fields

Everything else is a custom field defined on the object type in its group, read and written through customFieldValues. A “Job Applications” type can track a Status and an Interview date, while a “Partnerships” type tracks a Tier and a Renewal date.

To see the custom fields of an object type, call List group custom fields with the name of the object type as the entity type, for instance Job%20Applications. To add one, call Create a group custom field with the same entity type.

The following custom field types can be written on objects:

• textField
• numericField
• dateField
• singleSelect
• multipleSelect
• userField

contactField and objectField custom fields cannot be written on objects: an object type cannot have an objectField, and values sent for a contactField are not written. A contactField is always read back as an empty list.

Manage custom objects

Once the object type is defined in the group, its objects are created, read, updated and deleted with the custom object endpoints, with the name of the object type as the objectType path parameter.

List objects

GET /v1/groups/{groupId}/{objectType}

List the objects of one type in a group.

Create an object

POST /v1/groups/{groupId}/{objectType}

Create an object, with its people, companies and custom field values.

Get an object

GET /v1/groups/{groupId}/{objectType}/{objectId}

Retrieve one object by its ID.

Update an object

PATCH /v1/groups/{groupId}/{objectType}/{objectId}

Update the fields you send, and keep the others unchanged.

Delete an object

DELETE /v1/groups/{groupId}/{objectType}/{objectId}

Delete one object by its ID.

Create objects in batch

POST /v1/groups/{groupId}/{objectType}/batch/create

Create up to 100 objects of one type in a single request.

Update objects in batch

POST /v1/groups/{groupId}/{objectType}/batch/update

Update up to 100 objects of one type in a single request.

Delete objects in batch

POST /v1/groups/{groupId}/{objectType}/batch/delete

Delete up to 100 objects of one type in a single request.

Link people and companies

An object can reference up to 20 people and 20 companies, given by ID in the people and companies arrays of the request body. They must belong to the group of the object. A person or company that does not exist, or that is not in the group, is ignored: the request still succeeds, without it and without a warning. Check the people and companies of the returned object to know which ones were linked.

PATCH replaces the people and companies lists: to add a person to an object, read the object first, then send its current people plus the new one. Leave a list out to keep it unchanged.

Write custom field values

Custom field values are sent in the customFieldValues object of the request body, keyed by custom field name. A name that is not one of the custom fields of the object type fails the request with a 422.

Webhooks

Objects send object.created, object.updated and object.deleted webhook events. Their payloads differ from the people and companies ones:

• No groupId or objectType field. Read them from data.url, which is the URL of the object: https://api.folk.app/v1/groups/{groupId}/{objectType}/{objectId}.
• Custom field change paths have no group ID. An object.updated change on a custom field has the path ["customFieldValues", "Status"], since an object belongs to a single group.

Object relationships

People

Read more about people

Companies

Read more about companies

Objects are created inside a group, and the group defines the object types available to them.

Groups

Read more about groups