Quick start

Run your first API request and interact with your workspace data.

Prerequisites

Create a folk account if you don’t already have one yet. Sign up here.

Run your first API request

Step 1: Create a new API key

1. Go to the "Integrations" section of your workspace settings

   You can click on the “Settings” menu in the sidebar and then go to the “Integrations” section or follow this link directly

2. Click on the "API" section and generate a new API key

   
3. Copy the API key and save it in a secure location

   

Step 2: Use your terminal to run your first API request

Every request to the API needs to be authorized so that the system can identify you. To authorize your request, you need to pass your API key in the Authorization header using the bearer token scheme:

Authorization: Bearer YOUR_API_KEY

Let’s try to list all the groups available in our workspace. Use your favorite terminal app to run the following command:

  curl -X GET "https://api.folk.app/v1/groups" \
    -H "Authorization: Bearer YOUR_API_KEY"

Remember to replace YOUR_API_KEY with the API key you generated in step 1.

You should receive a response similar to this:

{
  "data":{
    "items":[
      {
        "id": "grp_12de8502-1832-4bd3-9cdf-2f0d8e0e1c22",
        "name": "Leads"
      },
      {
        "id": "grp_79b6ed73-9939-4118-ba65-7f8cdf401052",
        "name": "Clients"
      },
      {
        "id": "grp_39828bcf-97f4-407e-866e-a99e6242ccb8",
        "name": "Partners"
      }
    ],
    "pagination":{}
  }
}

Step 3: Create a new person in your workspace

Now that you know how to fetch information from your workspace, let’s try to add some new data.
We are going to create a new person called “John Doe” with the following attributes:

• First name: John
• Last name: Doe
• Email: [e-mail]
• Groups: Clients (id grp_79b6ed73-9939-4118-ba65-7f8cdf401052)

To do this, we need to use the POST method to send a request to the /v1/people endpoint.

  curl -X POST "https://api.folk.app/v1/people" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"firstName": "John", "lastName": "Doe", "groups": [{ "id": "grp_79b6ed73-9939-4118-ba65-7f8cdf401052" }], "emails": ["[e-mail]"]}'

Again, remember to replace YOUR_API_KEY with the API key you generated in step 1 and the group id with the one you retrieved in step 2.

You should receive a response similar to this:

{
  "data": {
    "id": "per_e2cbb1e5-c8b2-4f7b-8588-5952d6cc4acd",
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Doe",
    "description": "",
    "birthday": null,
    "jobTitle": "",
    "groups": [
      {
        "id": "grp_79b6ed73-9939-4118-ba65-7f8cdf401052",
        "name": "Clients"
      }
    ],
    "companies": [],
    "addresses": [],
    "emails": [
      "[e-mail]"
    ],
    "phones": [],
    "urls": [],
    "customFieldValues": {
      "grp_79b6ed73-9939-4118-ba65-7f8cdf401052": {}
    }
  }
}

If everything went well, you should be able to see the new person in your workspace in the “Clients” group.

Next steps

Now that you have seen how folk’s API works, you can start building your own integrations.
Before you start, we recommend to read about folk’s core concepts and data model in the next section. After that, you can check out the API reference to see the full list of endpoints and their documentation.