Address API - Backend Integration

Overview

Ingrid provides HTTP endpoints returning data in JSON format. We provide you with two environments:

• Stage - is our staging and testing environment where you do all the testing and developing against
  • https://api-stage.ingrid.com
  • Base url for Address API: https://api-stage.ingrid.com/address/v1
  • Swagger UI
  • Swagger JSON
• Production - is the production environment that you switch to when it’s time to go live
  • https://api.ingrid.com
  • Base url for Address API: https://api.ingrid.com/address/v1
  • Swagger UI
  • Swagger JSON

Api Basics

Authorization

When you register with Ingrid you will receive an API token. This token must be send with every request in the Authorization HTTP header with the Bearer prefix followed by base64 encoded token. Each request to our server will look more or less like:

> GET /address/v1/address_books/8cad4fce-06ae-4aaf-8eea-82cebbb301a5/contacts HTTP/2
> Host: api.ingrid.com
> Content-Type: application/json
> Accept: application/json
> Authorization: Bearer $PRIVATE_KEY_BASE64

Observability

All Ingrid responses will containt a x-trace-id header. In case of any problems or question, providing this value to us will allow us to go back to you with more accurate feedback.

< HTTP/2 200
< content-type: application/json
< x-trace-id: D20260128100011E5E41HYJJSPATG00
<
{...}

Errors

In case of any errors, Ingrid will return a 4xx or 5xx HTTP status code. The response body will contain a JSON object with the following structure:

{
  "error": "unauthenticated: rpc error: code = InvalidArgument desc = malformed authorization token",
  "trace_id": "D20260128095524VXP825X5YX020BMP"
}

For additional details about errors, please refer to the separate page: Errors.

Timeout

We recommend setting the timeout to 3 seconds for the Address API endpoints.

Api Integration

High Level Overview

The Address API is a RESTful API that contains multiple endpoints to support your custom address form frontend.

The main endpoint groups are:

Address Books: Manage user addresses efficiently with endpoints to create, read, update, and delete addresses associated with a user's account. More details can be found on the Address Books page.

Address Suggestions: Enhance the address entry experience by providing real-time address suggestions based on user input, improving accuracy and speed. More details can be found on the Address Suggestions page.

Address Validation: Ensure the accuracy of addresses entered by users by validating them against authoritative data sources and standardizing them for consistency. More details can be found on the Address Validation page.