Quick Start

This guide takes you from an empty integration to one successful API request. You will create an app, generate a scoped API key, collect your connection details, and request one record from your Workvivo organisation.

You are working with live data. Workvivo does not provide a sandbox or staging environment for API integrations. Your requests reach your production instance from the start, so begin with a read operation and keep the first response small.

1. Create an app

In Workvivo admin, open API Keys & JWT Settings and create an app for your integration.

An app is an organisational container for its API access. Creating one does not submit it to a marketplace or start a review process. A single app can have multiple API keys.

2. Generate an API key

Generate an API key for the app and select only the scopes the integration needs. For the request in this guide, include a scope that permits reading users.

The generated credential is a static API key. Send it as a Bearer token on every request:

Authorization: Bearer <key>

This is not an OAuth 2.0 access token and it is not a personal user-login token. Store the key as a secret and never embed it in source code.

3. Collect your connection details

The API Keys & JWT Settings section also displays the two values that identify where your requests should go:

• Base URL: the root URL for your organisation's API requests.
• Workvivo-Id: your organisation identifier, sent in the Workvivo-Id header on every request.

The examples below read the API key and organisation ID from environment variables:

WORKVIVO_TOKEN=<key>
WORKVIVO_ORG_ID=<Workvivo-Id>

They use https://api.workvivo.com/v1 as the Base URL. Never replace the environment variables in committed code with real credentials.

4. Make your first request

Start with GET /v1/users?take=1. It asks for at most one user from your organisation without changing any data.

Every request includes both access headers:

• Authorization: Bearer $WORKVIVO_TOKEN authenticates the API key.
• Workvivo-Id: $WORKVIVO_ORG_ID identifies the organisation.

curl -X GET "https://api.workvivo.com/v1/users?take=1" \
  -H "Authorization: Bearer $WORKVIVO_TOKEN" \
  -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
  -H "Accept: application/json"

const token = process.env.WORKVIVO_TOKEN;
const organisationId = process.env.WORKVIVO_ORG_ID;

if (!token || !organisationId) {
    throw new Error('Set WORKVIVO_TOKEN and WORKVIVO_ORG_ID before running this example.');
}

const response = await fetch('https://api.workvivo.com/v1/users?take=1', {
    headers: {
        Accept: 'application/json',
        Authorization: `Bearer ${token}`,
        'Workvivo-Id': organisationId,
    },
});

const body = await response.json();

if (!response.ok) {
    throw new Error(`Workvivo API request failed (${response.status}): ${JSON.stringify(body)}`);
}

console.log(body);

{
    "data": [
        {
            "id": 1,
            "external_id": "nk-3506",
            "email": "roma.baumbach@example.com",
            "name": "Roma Baumbach",
            "first_name": "Roma",
            "last_name": "Baumbach",
            "display_name": "Roma Baumbach",
            "avatar_url": "https://workvivo.com/img/roma-baumbach.jpg",
            "job_title": "Occupational Health Safety Technician",
            "timezone": "America/Bahia",
            "locale": "es_CO",
            "hire_date": "2013-08-04T17:21:16Z",
            "manager_id": null,
            "date_of_birth": null,
            "mobile_phone": null,
            "direct_dial": null,
            "has_logged_in": true,
            "is_frontline": false,
            "has_access": true,
            "created_at": "2025-01-01T00:00:00Z",
            "permalink": "https://workvivo.com/people/1"
        }
    ],
    "status": "success",
    "meta": {
        "pagination": {
            "skip": 0,
            "take": 1,
            "total_records": 125,
            "next_page": "https://api.workvivo.com/v1/users?take=1&skip=1"
        }
    }
}

Your values and records will differ, but the response demonstrates the common shape of a successful collection response:

• data contains the requested resources. For a collection endpoint, it is an array.
• status reports the outcome.
• meta contains supporting response information. Here, meta.pagination describes the current slice and provides the URL for the next one.

Different endpoints return different fields inside data; use the API reference for the resource you are working with.

If the request fails

Check the request from the outside in:

1. Confirm the request uses the Base URL shown in API Keys & JWT Settings.
2. Confirm the Authorization value starts with Bearer and uses the generated API key.
3. Confirm Workvivo-Id exactly matches the value shown in API Keys & JWT Settings.
4. Confirm the key has a scope that permits reading users.

Once this request succeeds, you have the same connection pattern used across the API: choose an endpoint, grant the required scope, then send the Bearer token and Workvivo-Id with the request.