Skip to main content

​
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 must 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 GroupData Available
Student & GraduateEmail Address, First Name, Last Name, Country, Institution, Date of Birth, Gender, Expiry Date, Graduation Year
Key Worker & Social Assistance GroupsEmail 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

​
Body Params

FieldTypeDescription
clientIdstringA unique ID provided by Pion
clientSecretstringA confidential, unique key provided by Pion
Example Request Body**_: _** 
{
  "clientId": "clientId",
  "clientSecret": "clientSecret"
}

​
Headers

Content-Typeapplication/json

​
Example Responses

​
200 OK

{
  "accessToken": "a1b2c3d4"
}

​
400 Bad Request

{
  "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

{
  "error": {
    "title": "unauthorised"
  }
}

​
[GET] /leads

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

​
Headers

Content-Typeapplication/json
AuthorizationBearer a1b2c3d4

​
Query Parameters

from (required)dd-mm-yyyy
to (required)dd-mm-yyyy
cursor (optional)<cursor returned from pion api leads response>

​
Example Responses

​
200 OK

{
  "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

{
  "error": {
    "title": "badRequest",
    "detail": "Reason for the failed request will be detailed here"
  }
}

​
401 Unauthorised

{
  "error": {
    "title": "unauthorised"
  }
}