InCountry POP API documentation

This document provides an overview and methods available in InCountry PoP API.

Overview

The InCountry PoP API is a set of RESTful methods that allow you to query regulated data from the InCountry platform without integrating the InCountry SDK into your application. It simplifies data communication and lets you quickly build applications with data localization capabilities. Unlike REST API, PoP API also supports MiniPoP’s, which extends the geography of applicability and data localization if comparing to MidPoP’s.

Authentication and authorization

The InCountry PoP API uses OAuth2 to authenticate and authorize requests with access tokens that are issued by the authentication server. To get a token, you need to create SDK credentials on the InCountry Portal and use the generated Client ID and Client Secret to get an access token for authorizing your data communication requests.

Requesting a token

POST https://{oauth_endpoint}/oauth2/token

Instead of the {oauth_endpoint} part, enter the address of the OAuth server depending on the region where the country is located.

EMEA: https://auth-emea.incountry.com/
APAC: https://auth-apac.incountry.com/

note

EMEA unites countries located in Europe, the Middle East, and Africa.

APAC unites countries located in the region around the Western Pacific Ocean.

TO FIND OUT THE APPROPRIATE OAUTH SERVER FOR YOUR COUNTRY, PLEASE CHECK THIS PAGE.

As authorization credentials, you need to pass the Client ID (as username) and Client Secret (as password) that you received on the InCountry Portal after creating SDK credentials. The authorization type should be basic authorization. It will transform authorization credentials into Base64 format.

Within the request body, you need to pass additional keys:

Key	Value	Description
`scope`	For example: `f2e5a966-1564-4c25-a3bf-0ef7a231fb2b`	Identifier of the environment within the target country. The environment ID should correspond to the authorization credentials (Client ID and Client Secret).
`audience`	For example: `https://us-mt-01.api.incountry.io https://nl-mt-01.api.incountry.io https://ru-mt-01.api.incountry.io`	You need to pass one or multiple addresses of PoP API servers separated by a whitespace. Such address looks like: `https://{country_code}-mt-01.api.incountry.io` The available countries are listed on this page. You need to locate the required country and use its country code (ISO format).
`grant_type`	`client_credentials`

cURL request

note

For the audience parameter, please use the available endpoints (country codes) that are listed on this page.

curl --location --request POST
--url 'https://{oauth_endpoint}/oauth2/token' \
--u 'your_client_id:your_client_secret' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'audience={popapi_address)' \
--data-urlencode 'scope={your_environment_id}'

As a response from the OAuth server, you will receive the following:

access_token - token string.
expires_in - life span of a generated token in seconds before it expires.
scope - environment ID.
token_type - bearer.

Once you have received the access token, use it for data management requests that you perform.

note

The access token is valid for 300 seconds, then it expires. You need further to get a new token by following the same approach.

Request headers

PoP API supports the following headers within requests:

Header	Format	Acceptable values	Description
`x-encrypted-storage`	string	`true` or `false`	Optional. This header regulates whether the server-side encryption (SSE) is applied. By default, it is set as `false` (SSE is disabled). Not all instances may have SSE feature supported.
`x-requested-at`	string	e.g. `2022-07-05T13:36:48.758405+00:00`	Optional. An idempotency header - used to avoid issues that may occur when sending duplicate non-idempotent (e.g. write) requests.

The following table illustrates support for specific headers by each type of the request.

Request	`x-encrypted-storage`	`x-requested-at`
Check the record’s status
Write a single record
Write multiple records
Read a single record
Find records
Delete a single record
Delete multiple records
Aggregate records
Upload a single file
Update a single file
Delete a single file
Download a single file
Get file metadata
Update file metadata

Getting started with PoP API

To get a comprehensive understanding of requests, endpoints, and data models in PoP API, please request the Swagger documentation from InCountry.

Managing records

The following section provides the list of methods that you can use to manage records stored on the InCountry platform.

Creating or updating a single record

POST /v2/storage/records/{country}

Creates or updates a single record on the InCountry platform in the target country. When using this method to update a record, you need to consider that it fully rewrites the initial record with a new payload. So you need to read the record first, make pointwise changes in the initial record, and then save this record to the InCountry platform keeping both old and updated values, otherwise old values may be fully overwritten with empty values.

Parameters

Parameter	Type	Example	Description
`country`	string (path)	`us`	Country code in ISO 3166-1 alpha-2 format.

Request body

application/json

Request body:

{
  "body": "string",
  "decimal_key1": 0,
  "decimal_key10": 0,
  "decimal_key11": 0,
  "decimal_key12": 0,
  "decimal_key13": 0,
  "decimal_key14": 0,
  "decimal_key15": 0,
  "decimal_key16": 0,
  "decimal_key17": 0,
  "decimal_key18": 0,
  "decimal_key19": 0,
  "decimal_key2": 0,
  "decimal_key20": 0,
  "decimal_key3": 0,
  "decimal_key4": 0,
  "decimal_key5": 0,
  "decimal_key6": 0,
  "decimal_key7": 0,
  "decimal_key8": 0,
  "decimal_key9": 0,
  "expires_at": "2023-03-08T12:49:30.812Z",
  "is_encrypted": true,
  "key": "string",
  "key1": "string",
  "key10": "string",
  "key11": "string",
  "key12": "string",
  "key13": "string",
  "key14": "string",
  "key15": "string",
  "key16": "string",
  "key17": "string",
  "key18": "string",
  "key19": "string",
  "key2": "string",
  "key20": "string",
  "key21": "string",
  "key22": "string",
  "key23": "string",
  "key24": "string",
  "key25": "string",
  "key3": "string",
  "key4": "string",
  "key5": "string",
  "key6": "string",
  "key7": "string",
  "key8": "string",
  "key9": "string",
  "parent_key": "string",
  "precommit_body": "string",
  "profile_key": "string",
  "range_key": 9223372036854776000,
  "range_key10": 9223372036854776000,
  "range_key2": 9223372036854776000,
  "range_key3": 9223372036854776000,
  "range_key4": 9223372036854776000,
  "range_key5": 9223372036854776000,
  "range_key6": 9223372036854776000,
  "range_key7": 9223372036854776000,
  "range_key8": 9223372036854776000,
  "range_key9": 9223372036854776000,
  "schema_id": "string",
  "schema_version": 0,
  "service_key1": "string",
  "service_key2": "string",
  "service_key3": "string",
  "service_key4": "string",
  "service_key5": "string",
  "version": 0
}

Responses

STATUS 201 - application/json A record has been created/updated successfully.

Response example:

{
  "attachments": "string",
  "body": "string",
  "created_at": "2023-03-08T12:49:30.821Z",
  "decimal_key1": 0,
  "decimal_key10": 0,
  "decimal_key11": 0,
  "decimal_key12": 0,
  "decimal_key13": 0,
  "decimal_key14": 0,
  "decimal_key15": 0,
  "decimal_key16": 0,
  "decimal_key17": 0,
  "decimal_key18": 0,
  "decimal_key19": 0,
  "decimal_key2": 0,
  "decimal_key20": 0,
  "decimal_key3": 0,
  "decimal_key4": 0,
  "decimal_key5": 0,
  "decimal_key6": 0,
  "decimal_key7": 0,
  "decimal_key8": 0,
  "decimal_key9": 0,
  "expires_at": "2023-03-08T12:49:30.821Z",
  "is_encrypted": true,
  "key1": "string",
  "key10": "string",
  "key11": "string",
  "key12": "string",
  "key13": "string",
  "key14": "string",
  "key15": "string",
  "key16": "string",
  "key17": "string",
  "key18": "string",
  "key19": "string",
  "key2": "string",
  "key20": "string",
  "key21": "string",
  "key22": "string",
  "key23": "string",
  "key24": "string",
  "key25": "string",
  "key3": "string",
  "key4": "string",
  "key5": "string",
  "key6": "string",
  "key7": "string",
  "key8": "string",
  "key9": "string",
  "parent_key": "string",
  "precommit_body": "string",
  "profile_key": "string",
  "range_key": 9223372036854776000,
  "range_key10": 9223372036854776000,
  "range_key2": 9223372036854776000,
  "range_key3": 9223372036854776000,
  "range_key4": 9223372036854776000,
  "range_key5": 9223372036854776000,
  "range_key6": 9223372036854776000,
  "range_key7": 9223372036854776000,
  "range_key8": 9223372036854776000,
  "range_key9": 9223372036854776000,
  "record_key": "string",
  "schema_id": "string",
  "schema_version": "string",
  "service_key1": "string",
  "service_key2": "string",
  "service_key3": "string",
  "service_key4": "string",
  "service_key5": "string",
  "updated_at": "2023-03-08T12:49:30.821Z",
  "version": 2147483647
}

STATUS 400 - application/json The server-side encryption (SSE) has failed.

STATUS 401 - application/json Unauthorized request.

STATUS 403 - application/json Encryption keys for the server-side encryption (SSE) have not been found for the specified client or country.

STATUS 409 - application/json Storage (PoP) for the specified country is not available.

STATUS 422 - application/json The request is invalid.

STATUS 503 - application/json Service is unavailable.

Creating or updating multiple records

POST /v2/storage/records/{country}/batchWrite

Creates or updates multiple records on the InCountry platform in the target country. When using this method to update multiple records, you need to consider that it fully rewrites the initial records with a new payload. So you need to read the records first, make pointwise changes in the initial records, and then save these records with updated values to the InCountry platform keeping both old and updated values, otherwise old values may be fully overwritten with empty values.

Parameters

Parameter	Type	Example	Description
`country`	string (path)	`us`	Country code in ISO 3166-1 alpha-2 format.

Request body

application/json

Request body:

{
  "records": [
    {
      "body": "string",
      "decimal_key1": 0,
      "decimal_key10": 0,
      "decimal_key11": 0,
      "decimal_key12": 0,
      "decimal_key13": 0,
      "decimal_key14": 0,
      "decimal_key15": 0,
      "decimal_key16": 0,
      "decimal_key17": 0,
      "decimal_key18": 0,
      "decimal_key19": 0,
      "decimal_key2": 0,
      "decimal_key20": 0,
      "decimal_key3": 0,
      "decimal_key4": 0,
      "decimal_key5": 0,
      "decimal_key6": 0,
      "decimal_key7": 0,
      "decimal_key8": 0,
      "decimal_key9": 0,
      "expires_at": "2023-03-08T12:50:46.601Z",
      "is_encrypted": true,
      "key": "string",
      "key1": "string",
      "key10": "string",
      "key11": "string",
      "key12": "string",
      "key13": "string",
      "key14": "string",
      "key15": "string",
      "key16": "string",
      "key17": "string",
      "key18": "string",
      "key19": "string",
      "key2": "string",
      "key20": "string",
      "key21": "string",
      "key22": "string",
      "key23": "string",
      "key24": "string",
      "key25": "string",
      "key3": "string",
      "key4": "string",
      "key5": "string",
      "key6": "string",
      "key7": "string",
      "key8": "string",
      "key9": "string",
      "parent_key": "string",
      "precommit_body": "string",
      "profile_key": "string",
      "range_key": 9223372036854776000,
      "range_key10": 9223372036854776000,
      "range_key2": 9223372036854776000,
      "range_key3": 9223372036854776000,
      "range_key4": 9223372036854776000,
      "range_key5": 9223372036854776000,
      "range_key6": 9223372036854776000,
      "range_key7": 9223372036854776000,
      "range_key8": 9223372036854776000,
      "range_key9": 9223372036854776000,
      "schema_id": "string",
      "schema_version": 0,
      "service_key1": "string",
      "service_key2": "string",
      "service_key3": "string",
      "service_key4": "string",
      "service_key5": "string",
      "version": 0
    },
    {
      "body": "string",
      "decimal_key1": 0,
      "decimal_key10": 0,
      "decimal_key11": 0,
      "decimal_key12": 0,
      "decimal_key13": 0,
      "decimal_key14": 0,
      "decimal_key15": 0,
      "decimal_key16": 0,
      "decimal_key17": 0,
      "decimal_key18": 0,
      "decimal_key19": 0,
      "decimal_key2": 0,
      "decimal_key20": 0,
      "decimal_key3": 0,
      "decimal_key4": 0,
      "decimal_key5": 0,
      "decimal_key6": 0,
      "decimal_key7": 0,
      "decimal_key8": 0,
      "decimal_key9": 0,
      "expires_at": "2023-03-08T12:50:46.601Z",
      "is_encrypted": true,
      "key": "string",
      "key1": "string",
      "key10": "string",
      "key11": "string",
      "key12": "string",
      "key13": "string",
      "key14": "string",
      "key15": "string",
      "key16": "string",
      "key17": "string",
      "key18": "string",
      "key19": "string",
      "key2": "string",
      "key20": "string",
      "key21": "string",
      "key22": "string",
      "key23": "string",
      "key24": "string",
      "key25": "string",
      "key3": "string",
      "key4": "string",
      "key5": "string",
      "key6": "string",
      "key7": "string",
      "key8": "string",
      "key9": "string",
      "parent_key": "string",
      "precommit_body": "string",
      "profile_key": "string",
      "range_key": 9223372036854776000,
      "range_key10": 9223372036854776000,
      "range_key2": 9223372036854776000,
      "range_key3": 9223372036854776000,
      "range_key4": 9223372036854776000,
      "range_key5": 9223372036854776000,
      "range_key6": 9223372036854776000,
      "range_key7": 9223372036854776000,
      "range_key8": 9223372036854776000,
      "range_key9": 9223372036854776000,
      "schema_id": "string",
      "schema_version": 0,
      "service_key1": "string",
      "service_key2": "string",
      "service_key3": "string",
      "service_key4": "string",
      "service_key5": "string",
      "version": 0
    }
  ]
}

Responses

STATUS 201 - application/jsonRecords have been created or updated successfully.

Response example:

{
  "records": [
    {
      "attachments": "string",
      "body": "string",
      "created_at": "2023-03-08T12:50:46.606Z",
      "decimal_key1": 0,
      "decimal_key10": 0,
      "decimal_key11": 0,
      "decimal_key12": 0,
      "decimal_key13": 0,
      "decimal_key14": 0,
      "decimal_key15": 0,
      "decimal_key16": 0,
      "decimal_key17": 0,
      "decimal_key18": 0,
      "decimal_key19": 0,
      "decimal_key2": 0,
      "decimal_key20": 0,
      "decimal_key3": 0,
      "decimal_key4": 0,
      "decimal_key5": 0,
      "decimal_key6": 0,
      "decimal_key7": 0,
      "decimal_key8": 0,
      "decimal_key9": 0,
      "expires_at": "2023-03-08T12:50:46.606Z",
      "is_encrypted": true,
      "key1": "string",
      "key10": "string",
      "key11": "string",
      "key12": "string",
      "key13": "string",
      "key14": "string",
      "key15": "string",
      "key16": "string",
      "key17": "string",
      "key18": "string",
      "key19": "string",
      "key2": "string",
      "key20": "string",
      "key21": "string",
      "key22": "string",
      "key23": "string",
      "key24": "string",
      "key25": "string",
      "key3": "string",
      "key4": "string",
      "key5": "string",
      "key6": "string",
      "key7": "string",
      "key8": "string",
      "key9": "string",
      "parent_key": "string",
      "precommit_body": "string",
      "profile_key": "string",
      "range_key": 9223372036854776000,
      "range_key10": 9223372036854776000,
      "range_key2": 9223372036854776000,
      "range_key3": 9223372036854776000,
      "range_key4": 9223372036854776000,
      "range_key5": 9223372036854776000,
      "range_key6": 9223372036854776000,
      "range_key7": 9223372036854776000,
      "range_key8": 9223372036854776000,
      "range_key9": 9223372036854776000,
      "record_key": "string",
      "schema_id": "string",
      "schema_version": "string",
      "service_key1": "string",
      "service_key2": "string",
      "service_key3": "string",
      "service_key4": "string",
      "service_key5": "string",
      "updated_at": "2023-03-08T12:50:46.606Z",
      "version": 2147483647
    },
    {
      "attachments": "string",
      "body": "string",
      "created_at": "2023-03-08T12:50:46.606Z",
      "decimal_key1": 0,
      "decimal_key10": 0,
      "decimal_key11": 0,
      "decimal_key12": 0,
      "decimal_key13": 0,
      "decimal_key14": 0,
      "decimal_key15": 0,
      "decimal_key16": 0,
      "decimal_key17": 0,
      "decimal_key18": 0,
      "decimal_key19": 0,
      "decimal_key2": 0,
      "decimal_key20": 0,
      "decimal_key3": 0,
      "decimal_key4": 0,
      "decimal_key5": 0,
      "decimal_key6": 0,
      "decimal_key7": 0,
      "decimal_key8": 0,
      "decimal_key9": 0,
      "expires_at": "2023-03-08T12:50:46.606Z",
      "is_encrypted": true,
      "key1": "string",
      "key10": "string",
      "key11": "string",
      "key12": "string",
      "key13": "string",
      "key14": "string",
      "key15": "string",
      "key16": "string",
      "key17": "string",
      "key18": "string",
      "key19": "string",
      "key2": "string",
      "key20": "string",
      "key21": "string",
      "key22": "string",
      "key23": "string",
      "key24": "string",
      "key25": "string",
      "key3": "string",
      "key4": "string",
      "key5": "string",
      "key6": "string",
      "key7": "string",
      "key8": "string",
      "key9": "string",
      "parent_key": "string",
      "precommit_body": "string",
      "profile_key": "string",
      "range_key": 9223372036854776000,
      "range_key10": 9223372036854776000,
      "range_key2": 9223372036854776000,
      "range_key3": 9223372036854776000,
      "range_key4": 9223372036854776000,
      "range_key5": 9223372036854776000,
      "range_key6": 9223372036854776000,
      "range_key7": 9223372036854776000,
      "range_key8": 9223372036854776000,
      "range_key9": 9223372036854776000,
      "record_key": "string",
      "schema_id": "string",
      "schema_version": "string",
      "service_key1": "string",
      "service_key2": "string",
      "service_key3": "string",
      "service_key4": "string",
      "service_key5": "string",
      "updated_at": "2023-03-08T12:50:46.606Z",
      "version": 2147483647
    }
  ]
}

STATUS 400 - application/json The server-side encryption (SSE) has failed.

STATUS 401 - application/json Unauthorized request.

STATUS 403 - application/json Encryption keys for the server-side encryption (SSE) have not been found for the specified client or country.

STATUS 409 - application/json Storage (PoP) for the specified country is not available.

STATUS 422 - application/json The request is invalid.

STATUS 503 - application/json Service is unavailable.

Reading a single record

GET /v2/storage/records/{country}/{record_key}

Reads a single record from the InCountry platform in a specific country.

Parameters

Parameter	Type	Example	Description
`country`	string (path)	`us`	Country code in ISO 3166-1 alpha-2 format.
`record_key`	string (path)	`a1d68d3b25d844ff91108b4e4c3d1667`	Record key specified during the record creation. Should be percent-encoded (RFC 3986) if contains any special characters in URI.

Responses

STATUS 200 - application/json The record has been read successfully.

Response example:

{
  "attachments": "string",
  "body": "string",
  "created_at": "2023-03-08T12:54:38.997Z",
  "decimal_key1": 0,
  "decimal_key10": 0,
  "decimal_key11": 0,
  "decimal_key12": 0,
  "decimal_key13": 0,
  "decimal_key14": 0,
  "decimal_key15": 0,
  "decimal_key16": 0,
  "decimal_key17": 0,
  "decimal_key18": 0,
  "decimal_key19": 0,
  "decimal_key2": 0,
  "decimal_key20": 0,
  "decimal_key3": 0,
  "decimal_key4": 0,
  "decimal_key5": 0,
  "decimal_key6": 0,
  "decimal_key7": 0,
  "decimal_key8": 0,
  "decimal_key9": 0,
  "expires_at": "2023-03-08T12:54:38.997Z",
  "is_encrypted": true,
  "key1": "string",
  "key10": "string",
  "key11": "string",
  "key12": "string",
  "key13": "string",
  "key14": "string",
  "key15": "string",
  "key16": "string",
  "key17": "string",
  "key18": "string",
  "key19": "string",
  "key2": "string",
  "key20": "string",
  "key21": "string",
  "key22": "string",
  "key23": "string",
  "key24": "string",
  "key25": "string",
  "key3": "string",
  "key4": "string",
  "key5": "string",
  "key6": "string",
  "key7": "string",
  "key8": "string",
  "key9": "string",
  "parent_key": "string",
  "precommit_body": "string",
  "profile_key": "string",
  "range_key": 9223372036854776000,
  "range_key10": 9223372036854776000,
  "range_key2": 9223372036854776000,
  "range_key3": 9223372036854776000,
  "range_key4": 9223372036854776000,
  "range_key5": 9223372036854776000,
  "range_key6": 9223372036854776000,
  "range_key7": 9223372036854776000,
  "range_key8": 9223372036854776000,
  "range_key9": 9223372036854776000,
  "record_key": "string",
  "schema_id": "string",
  "schema_version": "string",
  "service_key1": "string",
  "service_key2": "string",
  "service_key3": "string",
  "service_key4": "string",
  "service_key5": "string",
  "updated_at": "2023-03-08T12:54:38.997Z",
  "version": 2147483647
}

STATUS 400 - application/json The server-side encryption (SSE) has failed.

STATUS 401 - application/json Unauthorized request.

STATUS 403 - application/json Encryption keys for the server-side encryption (SSE) have not been found for the specified client or country.

STATUS 404 - application/json The requested record has not been found.

STATUS 409 - application/json Storage (PoP) in the specified country is not available.

STATUS 422 - application/json The request is invalid.

STATUS 503 - application/json Service is unavailable.

Deleting a single record

DELETE /v2/storage/records/{country}/{record_key}

Deletes a record in a specified country.

Parameters

Parameter	Type	Example	Description
`country`	string (path)	`us`	Country code in ISO 3166-1 alpha-2 format.
`record_key`	string (path)	`a1d68d3b25d844ff91108b4e4c3d1667`	The record key specified during the record creation. Should be percent-encoded (RFC 3986) if contains any special characters in URI.

Responses

STATUS 200 - application/json A record has been deleted successfully.

STATUS 401 - application/json Unauthorized request.

STATUS 404 - application/json The required field is missing in the data request.

STATUS 409 - application/json Storage (PoP) in the specified country is not available.

STATUS 422 - application/json The request is invalid.

STATUS 503 - application/json Service is unavailable.

Deleting multiple records

DELETE /v2/storage/records/{country}/batchDelete

Deletes multiple records from the InCountry platform in a specified country.

Parameters

Parameter	Type	Example	Description
`country`	string (path)	`us`	Country code in ISO 3166-1 alpha-2 format.

Request body

The request body contains the array of record keys (ids) that are subject to deletion.

application/json

Request body:

{
  "filter": {
    "key": [
      "string"
    ]
  }
}

Responses

STATUS 200 - application/json A record has been deleted successfully.

STATUS 401 - application/json Unauthorized request.

STATUS 409 - application/json Storage (PoP) in the specified country is not available.

STATUS 422 - application/json The request is invalid.

STATUS 503 - application/json Service is unavailable.

Getting the storage status for a record

GET /v2/storage/records/status/{country}/{record_key}

Gets the storage status for a specific record.

There are several possible statuses for a record:

Not found
Exists locally
Exists in transit
Exists remotely
Scheduled for deletion

The record passes 1 → 2 for MidPoP's and 1 → 3 → 4 for MiniPoP's.

Parameters

Parameter	Type	Example	Description
`country`	string (path)	`us`	Country code in ISO 3166-1 alpha-2 format.
`key`	string (path)	`a1d68d3b25d844ff91108b4e4c3d1667`	Record key specified at creation. Should be percent-encoded (RFC 3986) if contains any special characters in URI.

Responses

STATUS 200 - application/json A record is stored permanently.

Response example:

{
  "status": "Exists locally"
}

STATUS 202 - application/json A record is stored temporarily in the buffer.

Response example:

{
  "status": "Exists in transit"
}

STATUS 401 - application/json Unauthorized request.

STATUS 404 - application/json A record has not been found.

STATUS 409 - application/json Storage (PoP) in the specified country is not available.

STATUS 422 - application/json The request is invalid.

STATUS 503 - application/json Service is unavailable.

Searching for records

POST /v2/storage/records/{country}/find

Finds the records against specific search criteria.

Parameters

Parameter	Type	Example	Description
`country`	string (path)	`us`	Country code in ISO 3166-1 alpha-2 format.

Request body

The request body contains the search criteria that are used to find data records.

Request body:

{
  "filter": {
    "$or": [
      {
        "key": "string",
        "key1": "string",
        "key10": "string",
        "key11": "string",
        "key12": "string",
        "key13": "string",
        "key14": "string",
        "key15": "string",
        "key16": "string",
        "key17": "string",
        "key18": "string",
        "key19": "string",
        "key2": "string",
        "key20": "string",
        "key21": "string",
        "key22": "string",
        "key23": "string",
        "key24": "string",
        "key25": "string",
        "key3": "string",
        "key4": "string",
        "key5": "string",
        "key6": "string",
        "key7": "string",
        "key8": "string",
        "key9": "string",
        "parent_key": "string",
        "profile_key": "string",
        "range_key": 9223372036854776000,
        "range_key10": 9223372036854776000,
        "range_key2": 9223372036854776000,
        "range_key3": 9223372036854776000,
        "range_key4": 9223372036854776000,
        "range_key5": 9223372036854776000,
        "range_key6": 9223372036854776000,
        "range_key7": 9223372036854776000,
        "range_key8": 9223372036854776000,
        "range_key9": 9223372036854776000,
        "service_key1": "string",
        "service_key2": "string",
        "service_key3": "string",
        "service_key4": "string",
        "service_key5": "string"
      },
      {
        "key": "string",
        "key1": "string",
        "key10": "string",
        "key11": "string",
        "key12": "string",
        "key13": "string",
        "key14": "string",
        "key15": "string",
        "key16": "string",
        "key17": "string",
        "key18": "string",
        "key19": "string",
        "key2": "string",
        "key20": "string",
        "key21": "string",
        "key22": "string",
        "key23": "string",
        "key24": "string",
        "key25": "string",
        "key3": "string",
        "key4": "string",
        "key5": "string",
        "key6": "string",
        "key7": "string",
        "key8": "string",
        "key9": "string",
        "parent_key": "string",
        "profile_key": "string",
        "range_key": 9223372036854776000,
        "range_key10": 9223372036854776000,
        "range_key2": 9223372036854776000,
        "range_key3": 9223372036854776000,
        "range_key4": 9223372036854776000,
        "range_key5": 9223372036854776000,
        "range_key6": 9223372036854776000,
        "range_key7": 9223372036854776000,
        "range_key8": 9223372036854776000,
        "range_key9": 9223372036854776000,
        "service_key1": "string",
        "service_key2": "string",
        "service_key3": "string",
        "service_key4": "string",
        "service_key5": "string"
      }
    ],
    "created_at": "string",
    "expires_at": "string",
    "is_encrypted": true,
    "key": "string",
    "key1": "string",
    "key10": "string",
    "key11": "string",
    "key12": "string",
    "key13": "string",
    "key14": "string",
    "key15": "string",
    "key16": "string",
    "key17": "string",
    "key18": "string",
    "key19": "string",
    "key2": "string",
    "key20": "string",
    "key21": "string",
    "key22": "string",
    "key23": "string",
    "key24": "string",
    "key25": "string",
    "key3": "string",
    "key4": "string",
    "key5": "string",
    "key6": "string",
    "key7": "string",
    "key8": "string",
    "key9": "string",
    "parent_key": "string",
    "profile_key": "string",
    "range_key": 9223372036854776000,
    "range_key10": 9223372036854776000,
    "range_key2": 9223372036854776000,
    "range_key3": 9223372036854776000,
    "range_key4": 9223372036854776000,
    "range_key5": 9223372036854776000,
    "range_key6": 9223372036854776000,
    "range_key7": 9223372036854776000,
    "range_key8": 9223372036854776000,
    "range_key9": 9223372036854776000,
    "search_keys": "string",
    "service_key1": "string",
    "service_key2": "string",
    "service_key3": "string",
    "service_key4": "string",
    "service_key5": "string",
    "updated_at": "string",
    "version": 2147483647
  },
  "options": {
    "fields": [],
    "limit": 100,
    "offset": 0,
    "sort": []
  }
}

Responses

STATUS 200 - application/json Records matching search criteria have been found. The returned search results can include up to 100 data records per batch.

Response example:

{
  "data": [
    {
      "attachments": [
        {
          "created_at": "2023-03-08T12:56:47.432Z",
          "download_link": "string",
          "file_id": "string",
          "filename": "string",
          "hash": "string",
          "mime_type": "string",
          "size": 0,
          "updated_at": "2023-03-08T12:56:47.432Z"
        }
      ],
      "body": "string",
      "created_at": "2023-03-08T12:56:47.432Z",
      "decimal_key1": 0,
      "decimal_key10": 0,
      "decimal_key11": 0,
      "decimal_key12": 0,
      "decimal_key13": 0,
      "decimal_key14": 0,
      "decimal_key15": 0,
      "decimal_key16": 0,
      "decimal_key17": 0,
      "decimal_key18": 0,
      "decimal_key19": 0,
      "decimal_key2": 0,
      "decimal_key20": 0,
      "decimal_key3": 0,
      "decimal_key4": 0,
      "decimal_key5": 0,
      "decimal_key6": 0,
      "decimal_key7": 0,
      "decimal_key8": 0,
      "decimal_key9": 0,
      "expires_at": "2023-03-08T12:56:47.432Z",
      "is_encrypted": true,
      "key": "string",
      "key1": "string",
      "key10": "string",
      "key11": "string",
      "key12": "string",
      "key13": "string",
      "key14": "string",
      "key15": "string",
      "key16": "string",
      "key17": "string",
      "key18": "string",
      "key19": "string",
      "key2": "string",
      "key20": "string",
      "key21": "string",
      "key22": "string",
      "key23": "string",
      "key24": "string",
      "key25": "string",
      "key3": "string",
      "key4": "string",
      "key5": "string",
      "key6": "string",
      "key7": "string",
      "key8": "string",
      "key9": "string",
      "parent_key": "string",
      "precommit_body": "string",
      "profile_key": "string",
      "range_key": 9223372036854776000,
      "range_key10": 9223372036854776000,
      "range_key2": 9223372036854776000,
      "range_key3": 9223372036854776000,
      "range_key4": 9223372036854776000,
      "range_key5": 9223372036854776000,
      "range_key6": 9223372036854776000,
      "range_key7": 9223372036854776000,
      "range_key8": 9223372036854776000,
      "range_key9": 9223372036854776000,
      "schema_id": "string",
      "schema_version": 2147483647,
      "service_key1": "string",
      "service_key2": "string",
      "service_key3": "string",
      "service_key4": "string",
      "service_key5": "string",
      "updated_at": "2023-03-08T12:56:47.432Z",
      "version": 2147483647
    }
  ],
  "errors": [],
  "meta": {
    "count": 0,
    "limit": 0,
    "offset": 0,
    "total": 0
  }
}

STATUS 400 - application/json Server-side encryption (SSE) has failed.

STATUS 401 - application/json Unauthorized request.

STATUS 403 - application/json Search by searchable keys is not enabled in the target country.

STATUS 409 - application/json Storage (PoP) in the specified country is not available.

STATUS 422 - application/jsonThe request is invalid.

STATUS 503 - application/jsonService is unavailable.

Aggregating records

POST /v2/storage/records/{country}/aggregate

Aggregates records against specific attributes.

Parameters

Parameter	Type	Example	Description
`country`	string (path)	`us`	Country code in ISO 3166-1 alpha-2 format.

Request body

application/json

The request body contains the search criteria and aggregation parameters.

Request body:

{
  "filter": {},
  "group_by": {
    "cursor": {
      "after": [
        "string",
        0
      ]
    },
    "keys": [
      "profile_key"
    ],
    "limit": 100
  },
  "metrics": {
    "additionalProp1": {
      "func": "sum",
      "key": "range_key1"
    },
    "additionalProp2": {
      "func": "sum",
      "key": "range_key1"
    },
    "additionalProp3": {
      "func": "sum",
      "key": "range_key1"
    }
  },
  "next": "string"
}

Responses

STATUS 200 - application/json Returns aggregation results according to the passed parameters.

Response example:

{
  "data": [
    {
      "group": {
        "keys": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        }
      },
      "metrics": {
        "additionalProp1": 0,
        "additionalProp2": 0,
        "additionalProp3": 0
      }
    }
  ],
  "meta": {
    "next": "string"
  }
}

STATUS 400 - application/json Server-side encryption (SSE) has failed.

STATUS 401 - application/json Unauthorized request.

STATUS 403 - application/json Search by searchable keys is not enabled in the target country.

STATUS 409 - application/json Storage (PoP) in the specified country is not available.

STATUS 422 - application/jsonThe request is invalid.

STATUS 503 - application/jsonService is unavailable.

Managing attachments

The following section provides the list of methods that you can use to manage attachments stored on the InCountry platform.

Uploading a single attachment

POST /v2/storage/records/{country}/{record_key}/attachments

Uploads a single file to the InCountry platform under a particular data record.

Parameters

Parameter	Type	Required	Example	Description
`country`	string (path)		us	Country code in ISO 3166-1 alpha-2 format.
`record_key`	string (path)

Request body

multipart/form-data

Parameter	Type	Required	Example	Description
`file`	string($binary)

Responses

STATUS 201 - application/json A file has been uploaded successfully.

Response example:

{
  "created_at": "2023-03-08T12:58:02.639Z",
  "download_link": "string",
  "file_id": "string",
  "filename": "string",
  "hash": "string",
  "mime_type": "string",
  "size": 0,
  "updated_at": "2023-03-08T12:58:02.639Z"
}

STATUS 400 - application/json An error has occurred during the request parsing.

STATUS 401 - application/json Unauthorized request.

STATUS 403 - application/json Storage (PoP) in the specified country is not available.

STATUS 404 - application/json The record is unavailable in the storage.

STATUS 409 - application/json A file has not been uploaded as it already exists for the specified record.

STATUS 422 - application/json Only one file per request can be uploaded to the InCountry platform.

STATUS 503 - application/json Service is unavaiable.

Uploading or overwriting a single file

PUT /v2/storage/records/{country}/{record_key}/attachments

Uploads a file to InCountry Platform or overwrites it upon a conflict.

Parameters

Parameter	Type	Required	Example	Description
`country`	string (path)		us	Country code in ISO 3166-1 alpha-2 format.
`record_key`	string (path)

Request body

multipart/form-data

Parameter	Type	Required	Example	Description
`file`	string ($binary)

Responses

STATUS 201 - application/json A file has been uploaded successfully.

Response example:

{
  "created_at": "2023-03-08T12:58:17.613Z",
  "download_link": "string",
  "file_id": "string",
  "filename": "string",
  "hash": "string",
  "mime_type": "string",
  "size": 0,
  "updated_at": "2023-03-08T12:58:17.613Z"
}

STATUS 400 - application/json An error has occurred during the request parsing.

STATUS 401 - application/json Unauthorized request.

STATUS 403 - application/json Storage (PoP) in the specified country is not available.

STATUS 404 - application/json The record is unavailable in the storage.

STATUS 422 - application/json Only one file per request can be uploaded to the InCountry platform.

STATUS 503 - application/json Service is unavailable.

Deleting a single file

DELETE /v2/storage/records/{country}/{record_key}/attachments/{file_id}

Deletes a single file from the InCountry platform.

Parameters

Parameter	Type	Example	Description
`country`	string (path)	us	Country code in ISO 3166-1 alpha-2 format.
`record_key`	string (path)
`file_id`	string (path)

Responses

STATUS 204 - application/json A file has been deleted successfully.

STATUS 401 - application/json Unauthorized request.

STATUS 403 - application/json Storage (PoP) in the specified country is not available.

STATUS 404 - application/json A file has not been deleted as it was not found in the storage.

STATUS 422 - application/json Request is invalid.

STATUS 503 - application/json Service is unavailable.

Downloading a single file

GET /v2/storage/records/{country}/{record_key}/attachments/{file_id}

Downloads a specific file from the InCountry platform.

Parameters

Parameter	Type	Example	Description
`country`	string (path)	us	Country code in ISO 3166-1 alpha-2 format.
`record_key`	string (path)
`file_id`	string (path)

Responses

STATUS 200 - application/json A file has been downloaded successfully.

STATUS 401 - application/json Unauthorized request.

STATUS 403 - application/json Storage (PoP) in the specified country is not available.

STATUS 404 - application/json A file has not been deleted as it was not found in the storage.

STATUS 422 - application/json Request is invalid.

STATUS 503 - application/json Service is unavailable.

Reading the file’s metadata

GET /v2/storage/records/{country}/{record_key}/attachments/{file_id}/meta

Reads the file’s metadata from the InCountry platform.

Parameters

Parameter	Type	Example	Description
`country`	string (path)	us	Country code in ISO 3166-1 alpha-2 format.
`record_key`	string (path)
`file_id`	string (path)

Responses

STATUS 204 - application/json File’s metadata has been fetched successfully.

STATUS 401 - application/json Unauthorized request.

STATUS 403 - application/json Storage (PoP) in the specified country is not available.

STATUS 404 - application/json File’s metadata cannot be read as the file was not found in the storage.

STATUS 422 - application/json Request is invalid.

STATUS 503 - application/json Service is unavailable.

Updating the file’s metadata

PATCH /v2/storage/records/{country}/{record_key}/attachments/{file_id}/meta

Updates the file name and/or MIME type of the attachment.

Parameters

Parameter	Type	Example	Description
`country`	string (path)	us	Country code in ISO 3166-1 alpha-2 format.
`record_key`	string (path)
`file_id`	string (path)

Request body

Request example:

{
  "filename": "string",
  "mime_type": "string"
}

Responses

STATUS 204 - application/json File's metadata has been updated successfully.

Response example:

{
  "created_at": "2023-03-08T12:58:43.325Z",
  "download_link": "string",
  "file_id": "string",
  "filename": "string",
  "hash": "string",
  "mime_type": "string",
  "size": 0,
  "updated_at": "2023-03-08T12:58:43.325Z"
}

STATUS 401 - application/json Unauthorized request.

STATUS 403 - application/json Storage (PoP) in the specified country is not available.

STATUS 404 - application/json File’s metadata has not been updated as the file was not found in the storage.

STATUS 409 - application/json File’s metadata has not been updated as the file with the same name already exists.

STATUS 422 - application/json Request is invalid.

STATUS 503 - application/json Service is unavailable.

Structure of errors

PoP API may return errors when you perform invalid requests or the application is temporarily unavailable. Below you can find the structure of returned errors.

Field	Type	Description
`code`	string	Code of the occurred issue, for example `ERROR`.
`detail`	string	Detailed description of the occurred error.
`id_ext`	string	External correlation identifier of a specific request. It can be provided by the user to trace a request throughout the system.
`id_int`	string	Internal correlation identifier of a specific request. It is generated automatically.
`source`	string	A machine-readable object describing the error.
`status`	string	Status code of the occurred error.
`title`	string	Brief title of the occurred error.

Postman collection

To get started with InCountry PoP API, you can use the ready-to-use Postman collection and environment.

Instructions

Download the Postman collection and environment.
Import both files into Postman.
Open the imported environment and replace placeholders with credentials and endpoint details that you receive on the InCountry Portal.
Save modifications in the environment.
Open the imported collection and open the first request (from the collection) to acquire an access token. Ensure that you have selected the imported environment.
Run other requests from the collection to manage records and attachments.

Overview​

Authentication and authorization​

Requesting a token​

Request headers​

Getting started with PoP API​

Managing records​

Creating or updating a single record​

Parameters​

Request body​

Responses​

Creating or updating multiple records​

Parameters​

Request body​

Responses​

Reading a single record​

Parameters​

Responses​

Deleting a single record​

Parameters​

Responses​

Deleting multiple records​

Parameters​

Request body​

Getting the storage status for a record​

Parameters​

Responses​

Searching for records​

Parameters​

Request body​

Responses​

Aggregating records​

Parameters​

Request body​

Responses​

Managing attachments​

Uploading a single attachment​

Parameters​

Request body​

Responses​

Uploading or overwriting a single file​

Parameters​

Request body​

Responses​

Deleting a single file​

Parameters​

Responses​

Downloading a single file​

Parameters​

Responses​

Reading the file’s metadata​

Parameters​

Responses​

Updating the file’s metadata​

Parameters​

Responses​

Structure of errors​

Postman collection​

Overview

Authentication and authorization

Requesting a token

Request headers

Getting started with PoP API

Managing records

Creating or updating a single record

Parameters

Request body

Responses

Creating or updating multiple records

Parameters

Request body

Responses

Reading a single record

Parameters

Responses

Deleting a single record

Parameters

Responses

Deleting multiple records

Parameters

Request body

Getting the storage status for a record

Parameters

Responses

Searching for records

Parameters

Request body

Responses

Aggregating records

Parameters

Request body

Responses

Managing attachments

Uploading a single attachment

Parameters

Request body

Responses

Uploading or overwriting a single file

Parameters

Request body

Responses

Deleting a single file

Parameters

Responses

Downloading a single file

Parameters

Responses

Reading the file’s metadata

Parameters

Responses

Updating the file’s metadata

Parameters

Responses

Structure of errors

Postman collection