# Try It Function

Screenshot 2025-10-09 at 11.33.25.png
The Try It feature embedded in our API documentation lets you execute real API calls directly from the the docs UI.

Experiment, test requests, and verify responses directly in your chosen Firstup program without leaving the documentation environment.

## Prerequisites

* Know your server / base url:
  * US1: https://auth.socialchorus.com
  * US2: https://auth.us2.onfirstup.com
  * EU: https://auth.onfirstup.eu
* Request your bearer token, or client ID and secret from your Firstup representative.
* Select the program to connect to (e.g. your live environment, or a test environment).
* Your user or OAuth client has adequate permissions/role (e.g. “publisher” or higher) to call the endpoint you’re testing.


Because **Try It** sends actual API requests, avoid using it for destructive operations (DELETE, archive, etc.) in production unless you’re sure.

## 1: Authenticate

Select an API endpoint to try from our 
API reference 

.

Once you have selected an endpoint:

1. Select the **Try it** button.
2. Select your environment (top right-hand corner). The available options are:


* US1 region: https://auth.socialchorus.com
* US2 region: https://auth.us2.onfirstup.com
* EU region: https://auth.onfirstup.eu


Screenshot 2025-10-09 at 13.33.10.png
1. Select the **Environments** tab.
2. In the Inputs section, select the edit icon to enter your oauth type:


* oauth2_as_a_server_token or;
* oauth2_as_a_server_client_id
* oauth2_as_a_server_client_secret


Screenshot 2025-10-09 at 13.34.33.png
1. Select **Save**.


* Use Server Token when you already have an access token ready to paste in.
* Use Client ID and Secret when you want the **Try It** tool to handle token generation for you.


Once entered, your oauth details remain saved for all endpoints.

You can now make **live** API calls to your chosen environment.

## 2. Send a Request

### GET

For a basic example, we'll use a basic GET request to see which roles we have available in our program:


GET /scim/v2/roles 


1. Select **Try it**.
2. Find the response in the Response section.


For a GET request with query parameters, we'll try:


GET /v2/channels 


1. Select **Try it**.
2. In this example, the **Query** tab opens, with the following query options:


* `Filter.state`
* `page.size`
* `page.number`


1. Hovering over the info icon shows you what options are available.


* For example, the `filter.state` enum values: `archived`, `hidden`, `published`, `any`. For this example, enter `any`.
* For `page.size`, enter `20`.


1. Select **Send**.


tryitget.png
**Common responses**

* 200 — Success with JSON payload.
* 401 — Auth invalid/expired token or missing scopes.
* 404 — Resource not visible to the authed user.
* 400 — Invalid parameters.


For continous issues, see [Quick troubleshooting](https://developers.firstup.io/gettingstarted/try_it#quick-troubleshooting)

### POST

**Reminder**: This will create a real user in your program.

In this example, we'll create a user in your environment:


POST /scim/v2/users 


1. Select **Try it**.
2. Check you're still authenticated:


* Select either the environments tab (top-right).
* Or the security tab (under the endpoint).


tryitauthenticate.png
1. Fill out the body request in the **Body** tab. You can either amend and delete the example sample, or ask the AI search to give you the correct request body that includes all attributes you need.
2. Select Send.


For this example, we're sending basic details to create a user:

**Request example**


```
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:SocialChorus:1.0:User"
  ],
  "userName": "simonsmith",
  "name": {
    "givenName": "Simon",
    "familyName": "Smith"
  },
  "displayName": "ssmith",
  "externalId": "ext_123489",
  "nickName": "Si",
  "active": true,
  "roles": [
    {
      "type": "role",
      "value": "publisher"
    }
  ],
  "emails": [
    {
      "value": "simonsmith72@email.com",
      "primary": true,
      "type": "work"
    }
  ]
}
```

Screenshot 2025-10-09 at 11.20.27 copy.png
**Response example**


```
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    "urn:SocialChorus:1.0:User"
  ],
  "meta": {
    "resourceType": "User"
  },
  "id": 58706842,
  "active": true,
  "userName": "simonsmith",
  "externalId": "ext_123489",
  "programMembershipId": 133771663,
  "locale": null,
  "timezone": null,
  "title": null,
  "userType": null,
  "preferredLanguage": null,
  "emails": [
    {
      "value": "simonsmith72@email.com",
      "primary": true,
      "type": "work"
    }
  ],
  "roles": [
    {
      "type": "legacy_role",
      "value": "member"
    },
    {
      "type": "role",
      "value": "member"
    }
  ],
  "phoneNumbers": [],
  "addresses": [],
  "photos": [],
  "name": {
    "givenName": "Simon",
    "familyName": "Smith"
  },
  "displayName": "ssmith",
  "nickName": "Si",
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "organization": null,
    "employeeNumber": null,
    "department": null,
    "costCenter": null,
    "division": null
  },
  "urn:SocialChorus:1.0:User": {
    "birthDate": null,
    "hireDate": null,
    "businessUnit": null,
    "gender": null,
    "managerName": null,
    "workLocation": null,
    "promotionDate": null,
    "requisitionApprovalDate": null,
    "customAttributes": []
  }
}
```

Screenshot 2025-10-09 at 11.25.25 copy.png
**Common responses**

* 200 — Success with JSON payload.
* 401 — Auth invalid/expired token or missing scopes.
* 404 — Resource not visible to the authed user.
* 400 — Invalid parameters.


For continous issues, see [Quick troubleshooting](https://developers.firstup.io/gettingstarted/try_it#quick-troubleshooting)

## Alternatives

### Postman (optional)

1. From the [API landing page](https://developers.firstup.io/endpoints/openapi), download openapi.json or openapi.yaml.
2. Import into Postman to generate a collection.
3. Create an Environment with variables like `baseUrl` and `token`.
4. Set a **Pre-request Script** or **Authorization (Bearer Token)** to inject `Authorization: Bearer {{token}}`.
5. Select the request, set params, and Send.


Screenshot 2025-10-09 at 12.27.49.png
### cURL template (optional)


```
curl -i -X GET "<BASE_URL>/v2/feed/posts/{content_id}?locale=en" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json"
```

Base url:

* US1: https://auth.socialchorus.com
* US2: https://auth.us2.onfirstup.com
* EU: https://auth.onfirstup.eu


## Quick troubleshooting

* **Token expired**: Ensure you have a token that is valid
* **Missing scopes**: Ensure your OAuth app/access token includes the endpoint’s required scopes.
* **Wrong region**: The base URL must match your program’s region.
* **Visibility**: 404 often means the authed user cannot see that content.
* **Headers**: Don’t forget Authorization and Content-Type: application/json when needed.


### Common Errors

* **401**: Auth invalid/expired token or missing scopes.
* **404**: Resource not visible to the authed user.
* **400**: Invalid parameters.


### Ask AI Assistant

Ask our AI assistant to help troubleshoot issues:

1. Select the search bar.
2. Type in your question, copy any code, and give it the error code. You may want to also give it the endpoint. The more details it has, the better chance it has of troubleshooting.
3. Select Search with AI, or Ask AI Assistant.
4. This opens up your AI assistant chat bot. It may ask for more details if required.


Screenshot 2025-10-13 at 14.20.01.png