Introduction

API endpoint: https://giveclarity.co

Welcome to Clarity’s API reference! You can use these API endpoints to integrate with our platform.

View code examples in the dark area to the right, and explore specific endpoints by selecting them from the left-side navigation menu.

Authentication

To authorize your requests, please follow the steps:

Register with us as an organization.

Get your team's API key.

Send API key in the header with every request.

Please use the API key assigned to your team to access all of our API endpoints. You can register for a new API key by Getting Started as an organization through the landing page at www.giveclarity.co. If you are already our partner, please contact us at [email protected] to get authorized with a private key and to get started with utilizing our API.

Our API endpoints expects your team's API private key to be included in all API requests to the server. It must be included in a header using the following syntax:

Authorization: yourownkey

You must replace yourownkey with your personal API private key.

Endpoints

Get all the donors

Server will render all the donors in json format:

{
  "data": [
    {
      "id": "3758",
      "type": "donor",
      "attributes": {
        "first_name": "first",
        "last_name": "donor",
        "email": "[email protected]",
        "time_zone": null,
        "created_at": "2023-04-05T15:56:19.626Z",
        "updated_at": "2023-04-05T15:56:19.639Z",
        "birthday": "",
        "bio": " I am first donor",
        "username": "donor1",
        "phone": null,
        "avatar": ""
      }
    }
  ]
}

This endpoint retrieves all the donors associated with the team.

HTTPS Request

GET https://giveclarity.co/api/v1/donors

Request Header

Authorization header: yourownkey

Request Body

No request body is required for a successful API response.

Create a donor

Server will create a donor and render it in json format:

{
  "data": {
    "id": "3758",
    "type": "donor",
    "attributes": {
      "first_name": "first",
      "last_name": "donor",
      "email": "[email protected]",
      "time_zone": null,
      "created_at": "2023-04-05T15:56:19.626Z",
      "updated_at": "2023-04-05T15:56:19.639Z",
      "birthday": "",
      "bio": " I am first donor",
      "username": "donor1",
      "phone": null,
      "avatar": ""
    }
  }
}

This endpoint will create a donor in your team.

HTTPS Request

POST https://giveclarity.co/api/v1/donors

Request Header

Authorization header: yourownkey

Request Body

Please pass a FormData object in request body.

formData(first_name: String, last_name: String, email: String, username: String, birthday: String, bio: String, avatar: Image, custom_fields: [], beneficiary_ids: [])

custom_fields should be an array of objects with team_custom_field_id and value keys. for example: custom_fields: [{"team_custom_field_id": 1, "value": "test"}]

beneficiary_ids are used to create sponsorships. It should be an array of ids of beneficairies. for example: beneficiary_ids: [1, 2]

Get all the beneficiaries

Server will render all the beneficiaries in json format:

{
  "data": [
    {
      "id": "3812",
      "type": "beneficiary",
      "attributes": {
        "first_name": "first",
        "last_name": "beneficiary",
        "email": "[email protected]",
        "time_zone": null,
        "created_at": "2023-04-06T23:48:44.277Z",
        "updated_at": "2023-04-06T23:48:44.312Z",
        "birthday": "2023-03-14",
        "bio": "first test beneficiary",
        "username": "first1",
        "phone": null,
        "avatar": ""
      }
    }
  ]
}

This endpoint retrieves all the beneficiaries associated with the team.

HTTPS Request

GET https://giveclarity.co/api/v1/beneficiaries

Request Header

Authorization header: yourownkey

Request Body

No request body is required to pass with request.

Create a beneficiary

Server will create a beneficiary and render it in json format:

{
  "data": {
    "id": "3813",
    "type": "beneficiary",
    "attributes": {
      "first_name": "first",
      "last_name": "beneficiary",
      "email": "[email protected]",
      "time_zone": null,
      "created_at": "2023-04-07T00:24:59.163Z",
      "updated_at": "2023-04-07T00:24:59.198Z",
      "birthday": "2023-03-14",
      "bio": "first test beneficiary",
      "username": "first1",
      "phone": null,
      "avatar": ""
    }
  }
}

This endpoint will create a beneficiary in your team.

HTTPS Request

POST https://giveclarity.co/api/v1/beneficiaries

Request Header

Authorization header: yourownkey

Request Body

Please pass a FormData object in request body.

formData(first_name: String, last_name: String, email: String, username: String, birthday: String, bio: String, avatar: Image, custom_fields: [])

custom_fields should be an array of objects with team_custom_field_id and value keys. for example: custom_fields: [{"team_custom_field_id": 1, "value": "test"}]

Get all the posts of a team manager

Server will render all the posts of a team manager in json format:

[
  {
    "id": 1,
    "title": "first post",
    "user_id": 1,
    "created_at": "2023-04-07T01:13:07.776Z",
    "updated_at": "2023-04-07T01:13:07.786Z",
    "content": "This is a first post by manager",
    "approved_at": "2023-04-07T01:13:07.776Z",
    "approved_by": null,
    "published_at": "2023-05-01T00:00:00.000Z",
    "audience": 0,
    "preview_images": [],
    "audience_members_count": 3,
    "ordered_file_ids": [],
    "files": [""]
  }
]

This endpoint retrieves all the posts by a team manager.

HTTPS Request

GET https://giveclarity.co/api/v1/posts

Request Header

Authorization header: yourownkey

Request Body

No request body is required to pass with request.

Create a post as a team manager, as the manager, for donors, or for beneficiaries

Server will create a post and render it in json format:

{
  "id": 1,
  "title": "first post",
  "user_id": 1,
  "created_at": "2023-04-07T01:13:07.776Z",
  "updated_at": "2023-04-07T01:13:07.786Z",
  "content": "This is a first post by manager",
  "approved_at": "2023-04-07T01:13:07.776Z",
  "approved_by": null,
  "published_at": "2023-05-01T00:00:00.000Z",
  "audience": 0,
  "preview_images": [],
  "audience_members_count": 3,
  "ordered_file_ids": [],
  "files": []
}

This endpoint will create a post by team manager as a manager, a donor, or a beneficiary in your team.

HTTPS Request

POST https://giveclarity.co/api/v1/posts

Request Header

Authorization header: yourownkey

Request Body

Please pass a FormData object in request body.

formData(user_id: INT, title: String, content: String, published_at: Date as string, audience: [], files[]: [])

audience is an array of objects where every object's key is idof targeted audience. for example: audience: [{"id": "donors"}, {"id": "beneficiaries"}, {"id": "1"}]

user_id is an id of the user who is creating post. User can be a manager, a donor or a beneficiary.

Email invite to a user

Server will trigger an email invite to a user:

{
  "notice": "Invite sent successfully"
}

This endpoint will send an email invite to a user with a link to join your team.

HTTPS Request

POST https://giveclarity.co/api/v1/invites

Request Header

Authorization header: yourownkey

Request Body

Please pass a JSON object in request body.

{"user_id": INT, "message": STRING}

user_id is the id of a user. for example: {"user_id": 1, "message": "let's join!"}

Create a custom field

Server will render all custom fields of a team in JSON format:

[
  {
    "id": 1,
    "team_id": 5,
    "name": "first donor field",
    "value_type": "text",
    "record_type": "donor",
    "system_key": "first donor field",
    "editable": true,
    "visible": true,
    "system_owned": false,
    "created_at": "2023-04-07T02:06:08.811Z",
    "updated_at": "2023-04-07T02:06:08.811Z",
    "friendly_name": "Text"
  }
]

This endpoint will create a custom field for donors, beneficiaries, or sponsorships.

HTTPS Request

PATCH https://giveclarity.co/api/v1/custom_fields

Request Header

Authorization header: yourownkey

Request Body

Please pass a JSON object in request body.

{"name": STRING, "value_type": TEXT, LONG TEXT, DATE OR LINK, "record_type": STRING, "editable": boolean, "visible": boolean}

for example:

{"name": "first donor field", "value_type": "text", "record_type": "donor",
"editable": true, "visible": true}

Delete a custom field

Server will trigger an email invite to a user:

  "notice": "Custom field is deleted!"

This endpoint will delete a custom field if it's not a default custom field.

HTTPS Request

DELETE https://giveclarity.co/api/v1/custom_fields

Request Header

Authorization header: yourownkey

Request Body

Please pass a JSON object in request body.

{"id": INT, "record_type": STRING}

for example: {"id": 10, "record_type": "donor"}

Errors

The Clarity API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
400	Donor error messages.
400	Beneficiary error messages.
400	Post error messages.
401	Unauthorized -- Your API key is wrong.
404	Not Found -- Custom field not found.
422	Method Not Allowed -- Default field can not be deleted.
422	Method Not Allowed -- Please make sure the user exists to send invite.
422	Method Not Allowed -- User has no email to send the invite to.