# Quickstart: Your first API call

> Make your first Rippling API call using the GET List companies endpoint as a Hello World example.

Make your first Rippling API call using the GET List companies endpoint as a Hello World example.

## Overview

The Rippling REST API allows you to programmatically access and manage data in your Rippling account. With the API, you can build integrations, power automations, and extend Rippling's functionality to meet your organization's specific needs.

One advantage of using the REST API is that you can access Rippling data from any programming language or tool that supports HTTP requests, making it easy to integrate with your existing systems and workflows.

For example, in just a few minutes, you can quickly retrieve your company information, pull a list of employees, or automate the creation of new records.

### What can you do with the REST API?

| Operation | Example |
| --- | --- |
| Read company and employee data | Retrieve a list of all workers and their compensation details |
| Create and update records | Add a new department or update an employee's information |
| Manage custom objects | Create custom objects and populate them with data |
| Power automations | Trigger functions or sync data to external systems |
| Generate reports | Query data across multiple endpoints for custom reporting |

* * *

## Requirements

-   Rippling account with permission to **Create and manage API Tokens**.
-   [API token](https://developer.rippling.com/documentation/rest-api/essentials/api-tokens#create) - Required for authenticating API requests. Generate your token in the **Developer** app under the **API credentials** tab, and save it for later use.

* * *

## Make your first API call

In this tutorial, you'll use the **GET List companies** endpoint to verify your API setup is working correctly. This is a simple, read-only endpoint that returns information about your Rippling company.

### Generate your API token

1.  From the sidebar, select **Developer** > **API credentials** > **New API token**.
2.  Give your token a name (e.g., "Hello World Test").
3.  Select the `companies.read` scope.
4.  Click **Create** and copy your token value.

You can only view your API token once. Make sure to copy and store it securely before closing the dialog.

### Make the API request

Open your terminal and run the following command, replacing `YOUR_API_TOKEN` with the token you just created:

```bash
curl -X GET 'https://rest.ripplingapis.com/companies/' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

### Verify the response

A successful response returns a JSON object with your company data:

```json
{
  "results": [
    {
      "id": "507f1f77bcf86cd799439011",
      "created_at": "2023-01-15T08:00:00.000000+00:00",
      "updated_at": "2025-04-20T14:30:00.000000+00:00",
      "name": "Acme Corporation",
      "legal_name": "Acme Corporation Inc.",
      "primary_email": "admin@acme.com",
      "phone": "+1-555-123-4567",
      "physical_address": {
        "street_address": "123 Main St",
        "locality": "San Francisco",
        "region": "CA",
        "postal_code": "94105",
        "country": "US"
      }
    }
  ],
  "next_link": null
}
```

If you see your company data, congratulations! Your API setup is working correctly.

* * *

## Understand the response

| Field | Description |
| --- | --- |
| `results` | An array containing the company records returned by the API |
| `id` | The unique identifier for the company |
| `name` | The display name of the company |
| `legal_name` | The official legal name of the company |
| `physical_address` | The company's address information |
| `next_link` | A URL to fetch the next page of results (null if no more pages) |

### Why are some fields null?

Some fields in the response may return `null` for two reasons:

1.  **Expandable fields** - Fields like `legal_entities` require the `expand` query parameter to be populated. For example:
    
    ```bash
    curl -X GET 'https://rest.ripplingapis.com/companies/?expand=legal_entities' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer YOUR_API_TOKEN'
    ```
    
2.  **Permission restrictions** - Your API token may not have access to certain data. Check the `__meta.redacted_fields` array in the response to see which fields were hidden.
    

* * *

## Troubleshooting

### 401 Unauthorized

Your API token is missing or invalid. Double-check that:

-   The token is included in the `Authorization` header
-   The token is prefixed with `Bearer` (note the space)
-   The token hasn't been revoked or expired

### 403 Forbidden

Your API token doesn't have the required scope. Edit your token in the Developer app and ensure the `companies.read` scope is enabled.

### 429 Too Many Requests

You've exceeded the rate limit. Wait a few moments and try again. For production applications, implement exponential backoff. See [API usage and rate limits](https://developer.rippling.com/documentation/rest-api/essentials/api-limits) for more information.

* * *

## Next steps

Now that you've made your first API call, explore more of what the Rippling API can do:

-   [API tokens and permissions](https://developer.rippling.com/documentation/rest-api/essentials/api-tokens) - Learn about scopes and access control
-   [Query parameters](https://developer.rippling.com/documentation/rest-api/essentials/query-parameters) - Filter, expand, and sort your API responses
-   [REST API pagination guide](https://developer.rippling.com/documentation/rest-api/essentials/pagination) - Handle large result sets
-   [Get started with the HRIS API](https://developer.rippling.com/documentation/rest-api/guides/hris-getting-started) - Access employee and worker data

* * *

## See also

-   [Rippling API reference](https://developer.rippling.com/documentation/rest-api/reference/rippling-platform-api)
-   [Get started with the Rippling SDK](https://developer.rippling.com/documentation/js-sdk/getting-started)
-   [Postman](https://www.postman.com/) - A popular tool for testing APIs

Source: https://developer.rippling.com/documentation/rest-api/essentials/quickstart

> For the complete documentation index, see [llms.txt](https://developer.rippling.com/llms.txt). Public pages have a Markdown version at the same URL with .md added.