# API Open Endpoints

Open Endpoints are API calls designed for simplified use of the REST API functionality. The primary use case for the Open Endpoints is in **client-server** interactions, such as through a mobile app. These actions typically involve looking up information about an advocate or whom they’ve referred.

**Some examples include**:

* [Look up a referral code](https://integrations.impact.com/impact-brand/reference/openvalidatecode) after app install to display a dialog about who referred them
* [Register a new user](https://integrations.impact.com/impact-brand/reference/opencreateuser) in the referral program
* [Look up share links](https://integrations.impact.com/impact-brand/reference/opengetuser) to display a custom sharing dialog
* [Look up referrals](https://integrations.impact.com/impact-brand/reference/listreferrals) to display a list of referred friends

### Authentication options

* *Authentication via JSON Web Token (JWT)* - JWTs can be used for requests that require authentication. The process for building JWTs is outlined in our [JSON Web Tokens](/integration-guides/for-brands/advocate/advocate-tracking-integrations/json-web-tokens-jwts.md) documentation. Use for **client-server** communication.
* *Authentication via API Key* - Your API key can also be used for requests that require authentication. Use for **server-server** communication.
* *Unauthenticated* - Some Open Endpoints do not require any form of authentication.

#### Authentication Requirements by Method <a href="#authentication-requirements-by-method" id="authentication-requirements-by-method"></a>

The following table summarizes the Open Endpoint methods that are available for use, and their required level of authentication:

| Open Endpoint method                                                                                        | Authentication required    |
| ----------------------------------------------------------------------------------------------------------- | -------------------------- |
| [Create a user](https://integrations.impact.com/impact-brand/reference/opencreateuser)                      | Write Token or API key     |
| [Upsert a user](https://integrations.impact.com/impact-brand/reference/openuserupsert)                      | Write Token or API key     |
| [Look up a user](https://integrations.impact.com/impact-brand/reference/opengetuser)                        | Read Token or API key      |
| [Look up a user by referral code](https://integrations.impact.com/impact-brand/reference/opengetuserbycode) | No authentication required |
| [Look up a referral code](https://integrations.impact.com/impact-brand/reference/openvalidatecode)          | No authentication required |
| [Apply a referral code](https://integrations.impact.com/impact-brand/reference/openapplycode)               | Write Token or API key     |
| [List referrals](https://integrations.impact.com/impact-brand/reference/openlistreferrals)                  | Read Token or API key      |

#### Authentication with JWT

Authentication with JWTs should be used in **client-server**, not server-server communication.

The Advocate API accepts two types of JWTs: *read tokens* and *write tokens*. Read tokens are intended to validate a request to lookup information about an existing user/account while write tokens are intended to be used when adding or updating information about a user/account.

The format of the JWT payloads required for read and write tokens are outlined below:

**Read Token Payload**

The payload of a read token is based on the `user id` and `account id`:

{% tabs %}
{% tab title="JSON" %}

```json
{
  "user": {
    "id": "adfgafdg",
    "accountId": "adfklajdnrerereACdsedf"
  },
  "exp": 1462327764 
}
```

{% endtab %}
{% endtabs %}

**Write Token Payload**

The payload of a write token can contain the complete user object:

{% tabs %}
{% tab title="JSON" %}

```json
{
  "user": {
    "id": "adfgafdg",
    "accountId": "adfklajdnrerereACdsedf",
    "email": "bob@example.com",
    "firstName": "Bob",
    "lastName": "Testerson", 
    "locale": "en_US", 
    "referralCode": "BOBTESTERSON", 
    "imageUrl": "" 
  },
  "exp": 1462327764 
}
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
**Note:** The following fields are optional: `lastName`, `locale`, `referralCode`, `imageUrl`, and `exp` (expiry date in seconds since the epoch).
{% endhint %}

**Building the JWT**

{% hint style="info" %}
**Tip:** The process for building the JWT is outlined on our [JSON Web Tokens page](/integration-guides/for-brands/advocate/advocate-tracking-integrations/json-web-tokens-jwts.md).
{% endhint %}

Make sure that you are trying to sign the correct format of the payload (Read Token vs. Write Token) for your specific Open Endpoint API call.

#### Authentication with API Key

Authentication with your API key should be done when conducting **server-server** communication.

{% hint style="info" %}
**Tip:** Authenticating Open Endpoint calls with an API key is done in the same way as with our standard API calls, details for which can be found in [API Authentication](https://integrations.impact.com/impact-brand/docs/find-or-reset-an-api-key).
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-api/api-open-endpoints.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.