> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wearepion.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pion API

## Authentication at Pion

The Pion API provides an OAuth Client Credentials grant flow for accessing our services.

Client credentials can be self-served in the Pion Portal. This will create a new pairing of a clientId and clientSecret that is used to fetch an access token that ***<u>must</u>*** be passed into requests that require authentication.

Once you’ve got client credentials, you can send a request to the /auth/token endpoint. This is a post request with two body parameters.

**Client ID**

The Client ID is a unique identifier that is attached to your credentials by Pion. This should be considered sensitive data and stored securely.

**Client Secret**

The Client Secret is a confidential key that should be stored securely. This is used in conjunction with the Client ID to grant access to the Pion API.

This endpoint will return an access token that can then be used in subsequent requests that require authentication.

**Access Token**

A short-lived token that is used to verify that a client has permissions to access Pion data.

## Leads

The Lead Service captures rich, consented data directly from a brands verification integrations and marketplace, allowing you to enrich customer profiles and enhance your existing CRM. Leads are returned in batches of 1000. When a request has more than 1000 leads, an optional cursor attribute will be present in the response, which can be used to fetch the next batch of 1000 leads.

| **Consumer Group**                    | **Data Available**                                                                                              |
| :------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| Student & Graduate                    | Email Address, First Name, Last Name, Country, Institution, Date of Birth, Gender, Expiry Date, Graduation Year |
| Key Worker & Social Assistance Groups | Email Address, First Name, Last Name, Country                                                                   |

Once you have a valid access token, retrieved via the /auth endpoint. You can use this token to request lead data for your organisation. This is a GET request with two query parameters.

**From -** This is the date, formatted dd-mm-yyyy, that you would like the earliest lead data from.

**To -** This is the date, formatted dd-mm-yyyy, that you would like the latest lead data from.

**Cursor** **-** This is the optional reference object for the next item in the batch

This endpoint will return a list of the lead data between the two ranges.

# Technical Documentation

## \[POST] /auth/token

POST [https://api.wearepion.com/auth/token](https://api.wearepion.com/auth/token)

### Body Params

| **Field**        | **Type** | **Description**                             |
| :--------------- | :------- | :------------------------------------------ |
| **clientId**     | *string* | A unique ID provided by Pion                |
| **clientSecret** | *string* | A confidential, unique key provided by Pion |

*Example Request Body*\*\*:\*\*

```text theme={null}
{
  "clientId": "clientId",
  "clientSecret": "clientSecret"
}
```

### Headers

| Content-Type | application/json |
| :----------- | :--------------- |

### Example Responses

#### 200 OK

```text theme={null}
{
  "accessToken": "a1b2c3d4"
}
```

#### 400 Bad Request

```text theme={null}
{
  "error": {
    "title": "badRequest",
    "detail": "Reason for the failed request will be detailed here"
  }
}
```

Examples of the detail statement can be as follows:

* JSON body required
* clientId required
* clientSecret required

#### 401 Unauthorised

```text theme={null}
{
  "error": {
    "title": "unauthorised"
  }
}
```

## \[GET] /leads

GET [https://api.wearepion.com/leads?from=13-01-2026\&to=13-02-2026](https://api.wearepion.com/leads?from=13-01-2026\&to=13-02-2026)

### Headers

| Content-Type  | application/json |
| :------------ | :--------------- |
| Authorization | Bearer a1b2c3d4  |

### Query Parameters

| **from (required)**   | dd-mm-yyyy                                          |                                                                                                                                                                                                                                                  |
| :-------------------- | :-------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| to (required)         | dd-mm-yyyy                                          |                                                                                                                                                                                                                                                  |
| cursor **(optional)** | **\<cursor returned from pion api leads response>** |                                                                                                                                                                                                                                                  |
| fields **(optional)** |                                                     | comma separated string of desired response fields in snakecase, <br />eg. fields\[lead]=email,institution,grad\_year options: `lead_type` `sbid` `email` `first_name` `second_name` `gender` `date_of_birth` `country` `institution` `grad_year` |

### Example Responses

#### `GET https://api.wearepion.com/leads?from=13-01-2026&to=13-02-2026`

A request for leads data that does not contain the `fields` query parameter will return all available leads data within range.

```text theme={null}
{
  "leads": [
    {
      "lead_type": "online",
      "sbid": "someUserId",
      "email": "someuser@mail.com",
      "first_name": "Nicholas",
      "second_name": "Angel",
      "gender": "M",
      "date_of_birth": "2000-02-22",
      "country": "UK",
      "institution": "Canterbury University",
      "grad_year": 2024
    }
  ],
  cursor: "example_cursor"
}
```

#### 400 Bad Request

```text theme={null}
{
  "error": {
    "title": "badRequest",
    "detail": "Reason for the failed request will be detailed here"
  }
}
```

#### 401 Unauthorised

```text theme={null}
{
  "error": {
    "title": "unauthorised"
  }
}
```

## \[GET] /leads - Request Selected Fields Only

Using the optional fields query parameter you may request leads data to return only selected fields.

Available fields:

* lead\_type
* sbid
* email
* first\_name
* second\_name
* gender
* date\_of\_birth
* country
* institution
* grad\_year

### Example Responses

#### 200 OK

`GET https://api.wearepion.com/leads?from=13-01-2026&to=13-02-2026&fields[lead]=email,institution,grad_year`

```text theme={null}
{
  "leads": [
    {
      "email": "someuser@mail.com",
      "institution": "Canterbury University",
      "grad_year": 2024
    }
  ],
  cursor: "example_cursor"
}
```

#### 422 Bad Request

`GET https://api.wearepion.com/leads?from=13-01-2026&to=13-02-2026&fields[lead]=email,institution,potatoes`

```text theme={null}
{
  "error": {
    "title": "UnprocessableEntityError",
    "detail": ["Invalid fields in fields[lead] parameter: nonexistentfield. Valid fields are: organisation_uid, created_at, lead_type, sbid, brand_uid, email, first_name, second_name, gender, date_of_birth, country, institution, grad_year, group, additional_info"]
  }
}
```

#### 422 Bad Request

`GET https://api.wearepion.com/leads?from=13-01-2026&to=13-02-2026&fields[lead]=`

```text theme={null}
{
  "error": {
    "title": "UnprocessableEntityError",
    "detail": ["fields[lead] parameter must not be empty"]
  }
}
```