Getting Started with the Apricot API

What You Need

To make your first API call, you need two things:

An Access Token - Proves who you are
The API Base URL - Where to send requests

Let's get started.

Get Your Access Token

You'll Need:

Client ID - Get this from your Apricot admin
Client Secret - Get this from your Apricot admin

Option A: Using cURL

curl -X POST "https://api.bonterra.network/v1/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "audience=https://api.bonterra.network"

Option B: Using Postman

Create a new request in Postman
Set method to POST
Enter URL: https://api.bonterra.network/v1/oauth/token
Go to the Headers tab:
- Add Content-Type: application/x-www-form-urlencoded
Go to the Body tab:
- Select x-www-form-urlencoded
- Add these key-value pairs:
  - grant_type: client_credentials
  - client_id: YOUR_CLIENT_ID
  - client_secret: YOUR_CLIENT_SECRET
  - audience: https://api.bonterra.network
Click Send

You'll get back:

{
  "access_token": "eyJhVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Copy that access_token - you'll use it for every API call.

Make Your First API Call

Now test it by getting your user info:

Option A: Using cURL

curl -X GET "https://api.bonterra.network/v1/apricot/users" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Option B: Using Postman

Create a new request in Postman
Set method to GET
Enter URL: https://api.bonterra.network/v1/apricot/users
Go to the Headers tab:
- Add Authorization: Bearer YOUR_ACCESS_TOKEN
- (Replace YOUR_ACCESS_TOKEN with the token from Step 1)
Click Send

If it works, you'll see:

{
  "data": {
    "id": "123",
    "type": "users",
    "attributes": {
      "email": "you@example.org",
      "first_name": "Your Name",
      "role": "Program Manager"
    }
  }
}

✅ Success! You're connected to the API.

Postman Pro Tips

Save Your Access Token as a Variable

In Postman, click the Environment dropdown (top right)
Create a New Environment (e.g., "Apricot API")
Add a variable:
- Variable: access_token
- Initial Value: (paste your token here)
- Current Value: (paste your token here)
Save the environment
Now in your requests, use {{access_token}} instead of the actual token:
- Header: Authorization: Bearer {{access_token}}

Create a Collection

Create a new Collection called "Apricot API"
In the Collection settings, go to Authorization:
- Type: Bearer Token
- Token: {{access_token}}
Set Auth Type to "Inherit auth from parent"
Now all requests in this collection will automatically include your token! 🎉

Common API Calls in Postman

Get All Forms

Method: GET
URL: https://api.bonterra.network/v1/apricot/forms
Headers: Authorization is inherited from collection

Create a Record

Method: POST
URL: https://api.bonterra.network/v1/apricot/records
Headers: Authorization (inherited), Content-Type: application/json
Body (raw JSON):

{
  "data": {
    "type": "records",
    "attributes": {
      "form_id": 2,
      "programs": [2],
      "field_2_first": "John",
      "field_2_last": "Doe",
      "field_96": "Active"
    }
  }
}

Get a Specific Record

Method: GET
URL: https://api.bonterra.network/v1/apricot/records/12345
Headers: Authorization is inherited

Update a Record

Method: PUT
URL: https://api.bonterra.network/v1/apricot/records/12345
Headers: Authorization (inherited), Content-Type: application/json
Body (raw JSON):

{
  "data": {
    "type": "records",
    "id": "12345",
    "attributes": {
      "field_96": "Inactive"
    }
  }
}

Search Records

Method: POST
URL: https://api.bonterra.network/v1/apricot/records/search
Headers: Authorization (inherited), Content-Type: application/json
Body (raw JSON):

{
  "form_id": 2,
  "filters": {
    "field_96": "Active"
  }
}

Quick Reference

Most API calls follow this pattern:

In cURL:

curl -X [METHOD] "https://api.bonterra.network/v1/apricot/[ENDPOINT]" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Note: Some endpoints use different content types. For example, uploading attachments requires multipart/form-data instead of application/json.

In Postman:

Set the Method (GET, POST, PUT, etc.)
Set the URL: https://api.bonterra.network/v1/apricot/[ENDPOINT]
Add Authorization header (or inherit from collection)
For POST/PUT, add Body with JSON data

What's Next?

Once you can make that first call, you can:

List forms: GET /forms
Get form fields: GET /forms/{id}/fields
Create records: POST /records
Search data: POST /records/search
Upload attachments: POST /records/{id}/attachment/{field_id}

Ready for More?

Check the full API documentation for detailed endpoint information.

View Full Documentation →