API Reference
The Gaya API is organized around REST principles. It features predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Installation Guide
To test on the dev environment, please follow these steps:
Download
Google ChromeDownload the latest build of the
Gaya browser extensionInstall the downloaded Gaya browser extension on Google Chrome
3.1 Click on the extension icon in Google Chrome, and select "Manage extensions"
3.2 Enable Developer Mode by setting the Developer mode toggle to true
3.3 Click on "Load Unpacked" and select the unzipped extension file to upload it
Pin the Gaya browser extension to your toolbar and log in using your Gaya account credentials
Learn More
Stay updated with the latest insights, features, and best practices for using our product by visiting our
Authentication
An account with a registered email address and password is required to use the API. If you don't have an account, please contact [email protected] to request one.
API Location
The API is available at https://prod-api.gaya.ai. Responses are formatted and sent as JSON objects.
HTTP Verbs
The Gaya API uses HTTP verbs appropriate to each action.
| Verb | Description |
|---|---|
| GET | Retrieving resources |
| POST | Creating resources |
| PUT | Updating resources |
| DELETE | Deleting resources |
Error Handling
If an error occurs, whether on the server or client side, the error message(s) will be returned in an error object. For example:
{
"status": 405,
"name": "MethodNotAllowedError",
"message": "The requested HTTP method is not allowed for this resource",
"details": null
}We use conventional HTTP response codes to indicate the success or failure of an API request.
In general, codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with Gaya's servers.
| HTTP Status Code | Description |
|---|---|
| 200 - OK | Everything worked as expected |
| 201 - Created | The request was successful and a resource was created |
| 202 - Accepted | The request has been received and accepted for processing, but is not yet completed |
| 400 - Bad Request | The request was unacceptable, often due to missing a required parameter |
| 401 - Unauthorized | No valid API key provided |
| 403 - Forbidden | The API key doesn't have permissions to perform the request |
| 404 - Not Found | The requested resource doesn't exist |
| 405 - Method Not Allowed | You tried to access a resource with an invalid method |
| 422 - Unprocessable Entity | The request was well-formed but was unable to be followed due to semantic errors |
| 409 - Conflict | The request could not be completed due to a conflict with the current state of the target resource |
| 429 - Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests |
| 500, 503 - Server Errors | Something went wrong on our end. (These are rare) |
Entities and Fields
Entities are higher-level objects in our API that represent data like cars or customers that can have many attributes. Entities are categorized as either indexable or non-indexable based on how many times they can appear in a single context.
Fields are attributes of an entity. For example, a "car" entity might have fields like "make," "model," and "year".
Indexable entities
Indexable entities can appear multiple times in the same context. For example, a single insurance policy can cover multiple cars. Each car needs a unique index number (1, 2, 3, etc.) to identify it correctly. Each "Car" entity will have its own set of fields to store details about each car.
Special Note: The "household" entity is a unique indexable entity. The first household member is assumed to be the customer. Therefore, additional household entities start with index 2 (2, 3, 4, etc.).
Non-indexable entities
Non-indexable entities can only appear once in the same context. For example, there can only be one customer per insurance policy. Non-indexable entities are always referenced with the index number 1.
| Entity Type | Entity Name | Index Requirement |
|---|---|---|
| Indexable | Household | 2 or greater |
| Indexable | Car | 1 or greater |
| Indexable | Loss | 1 or greater |
| Indexable | Accident/Violation | 1 or greater |
| Indexable | Additional Interest | 1 or greater |
| Non-indexable | Home Policy | 1 |
| Non-indexable | Customer (required entity) | 1 |
| Non-indexable | Auto Commercial Insurance | 1 |
| Non-indexable | Auto Policy | 1 |
| Non-indexable | Property | 1 |
Authentication Methods
When interacting with the Gaya API, you have several options for authenticating your API requests. The API provides two primary authentication methods: