For AI agents: an index of this documentation is at https://developer.rippling.com/llms.txt. Public pages have a Markdown version at the same URL with .md added.

Skip to main content
REST API
guide

Quickstart: Your first API call

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

Use with AI:Rippling AI ChatGPT Claude Cursor

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?​

OperationExample
Read company and employee dataRetrieve a list of all workers and their compensation details
Create and update recordsAdd a new department or update an employee's information
Manage custom objectsCreate custom objects and populate them with data
Power automationsTrigger functions or sync data to external systems
Generate reportsQuery data across multiple endpoints for custom reporting

Requirements​

  • Rippling account with permission to Create and manage API Tokens.
  • API token - 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:

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:

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

FieldDescription
resultsAn array containing the company records returned by the API
idThe unique identifier for the company
nameThe display name of the company
legal_nameThe official legal name of the company
physical_addressThe company's address information
next_linkA 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:

    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 for more information.

Next steps​

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

See also​

In this article: