Amazon Data Portability API references
- Version information
- License information
- Consumes
- Produces
- Endpoints
- External Docs
- Operations
- Paths
- Response Notification
- Error Responses and Schemas
- Definitions
Amazon Data Portability lets you import customer data to your Application provided the customers give authorization.
Version information
- Version: 2024-02-29
License information
- License: Amazon Software License
- License URL: https://aws.amazon.com/asl/
Consumes
application/json
Produces
application/json
Endpoints
| Endpoint | Region |
|---|---|
| intake.eu-west-1.portability.data.amazon | Europe (Dublin) |
| intake.us-east-1.portability.data.amazon | US East (N. Virginia) |
| intake.us-west-2.portability.data.amazon | US West (Oregon) |
📘 You have an option to switch anytime between regions because all responses will be synced.
External Docs
- Description : Learn more about Amazon.
- URL : https://developer.amazon.com
Operations
📘 Responses for all operations have a five minute, time-to-live (TTL) based on the authorization check. During the five-minute period, the API will return the same response for the same parameters.
Paths
Create Data Query
POST /{scopeId}/data-queries
Operation:
createDataQuery
Description:
Use the createDataQuery operation to start requesting authorized customer data.
The request will start in the Amazon Data Portability API, an async task that will start the request to gather data, and, at the same time will return the
queryId that identifies the request from the async task.
The Amazon Data Portability API has throttling limits configuration to protect against burst traffic and ensure service availability. Requests that have been throttled will return a 429 HTTP status code. Values setup for this operation:
| Rate Limit | Burst Limit | Daily Quota |
|---|---|---|
| 1 | 1 | 1500 |
Where:
Rate limit is the number of requests allowed in a second for an Application.
Burst limit is the number of requests the API can handle concurrently for an Application.
Daily quota is the total quota the API can handle in a day for each Application and scope.
Parameters:
| Type | Name | Description | Schema | Example |
|---|---|---|---|---|
| Path | scopeId required |
The Amazon Data Portability LWA scopeId to use when calling the Amazon Data Portability API.
See Amazon Data Portability Available LWA Scopes for details. |
string | portability-physical-orders |
| Header | authorization required |
The LWA access token to use when calling the Amazon Data Portability API. | string | Bearer Atza|IgEBIJBAxValidAccessToken |
Only one request for customer and scopeId can be computed at a time.
If there’s a request in progress and in a non-terminal state (not COMPLETED or CANCELED), the API will return a CONFLICT error.
Responses:
| HTTP Code | Description | Schema |
|---|---|---|
| 201 | The query call is successful. | CreateDataQueryOutput |
| 400 | The service was unable to process your request. Reasons for the error are described in an error response object. | ErrorResponse |
For additional error status codes, descriptions and schemas, see Error responses and schemas.
Amazon Data Portability API returns forbidden or invalid token errors if (1) authorization expired, (2) the customer revoked the authorization, or (3) the account is on hold.
List Data Query Records
GET /{scopeId}/data-queries/{queryId}/records
Operation:
listDataQueryRecords
Description:
Use the listDataQueryRecords operation to view all customer data and port it in your Application.
Use this operation for queries that have been marked with COMPLETED status.
For queries that have a different status, the API will return an error.
List Data Query Records will return results for a query after the notification response has been sent. Each file and schema link will be available for five minutes from the time the response was sent, and you can perform the same list operation for the same query for at most 1 hour after the response notification has been sent. All schemas and responses from a List Data Query Record, after download, will be at 2GB max.
The Amazon Data Portability API has throttling limits configuration to protect against burst traffic and ensure service availability. Requests that have been throttled will return a 429 HTTP status code. Values setup for this operation:
| Rate Limit | Burst Limit | Daily Quota |
|---|---|---|
| 2 | 1 | 10000 |
Where:
Rate limit is the number of requests allowed in a second for an Application.
Burst limit is the number of requests the API can handle concurrently for an Application.
Daily quota is the total quota the API can handle in a day for each Application and scope.
Parameters
| Type | Name | Description | Schema | Default | Example |
|---|---|---|---|---|---|
| Path | scopeId required |
The Amazon Data Portability LWA scopeId to use when calling the Amazon Data Portability API.
See Amazon Data Portability Available LWA Scopes for details. |
string | - | portability-physical-orders |
| Path | queryId required |
The queryId that was completed and to use when calling the API. |
UUID | - | a1111111-b222-c333-d444-e55555555555 |
| Query | maxResults optional |
The maximum number of records to be returned in the response of the API call. Value is between 1 and 250. | integer | 250 | 200 |
| Query | nextPageToken optional |
A page token returned in the response to your previous request. The nextPageToken is returned when the number of results exceed the page size. To get the next page of results, include nextPageToken as parameter. When no nextPageToken value is returned, there are no more records to return. |
string | empty | StringWithNextPageTokenValue123---== |
| Header | authorization required |
The LWA access token to use when calling the Amazon Data Portability API. | string | - | Bearer Atza|IgEBIJBAxValidAccessToken |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Product successfully retrieved. | ListDataQueryRecordsOutput |
| 400 | The service was unable to process your request. Reasons for the error are described in an error response object. | ErrorResponse |
For additional error status codes, descriptions and schemas, see Error responses and schemas.
Amazon Data Portability API returns forbidden or invalid token errors if (1) authorization expired, (2) the customer revoked the authorization, or (3) the account is on hold.
Response Notification
Description:
Once the create data query has reached its final state, Amazon Data Portability API sends a notification response, through a POST method, on your HTTPS endpoint. The API sends the response to the same region you sent the create request. The notification file size is at 1KB max. You can perform List Data Query Records operations for the same query for at most 1 hour after the response notification has been sent.
Amazon Data Portability API includes the notification version number in the response. Consider including the version number at the end of the HTTP path. For
example, if your HTTPS endpoint is https://myapp/notifications, use https://myapp/notifications/v1 for version 1.
Available supported versions: 1.0
Latest supported version: 1.0
📘 You have an option to change the HTTPS endpoints by submitting a case through a Contact Us in Developer Portal. In the category section, select "Amazon Data Portability". In the topic section, select "Allowlisting & Integration Updates". Provide the details related to your new HTTPS endpoints.
Responses:
The notification has the HTTP/HTTPS notification JSON format.
| Entry | Description | Schema |
|---|---|---|
| Subject | The subject of the notification sent on the HTTPS endpoint. | ResponseNotificationSubject |
| Message | Details the specific notification that was sent after the customer data has been collected. | ResponseNotificationMessage |
📘 The Application is automatically subscribed to the notification version number available during Application submission. After Application submission, and if a new notification version becomes available, you have an option to request for the new version.
To opt-in to a new version, go to Contact Us in the Developer Portal. In the Category section, select "Amazon Data Portability". In the Topic section, select "Allowlisting & Integration Updates". Provide details related to your HTTPS endpoints.
Error Responses and Schemas
The Application must handle any standard HTTP response code that could result from a web service call. All APIs return an HTTP response code of 200 or 201 if the call was successfully received and processed. Any errors that occurred during processing are detailed in the response with corresponding status code.
| HTTP Code | Category, Type & Message | Details | Schema |
|---|---|---|---|
| 400 Bad Request |
Category: BAD_REQUEST Type: INVALID_PARAMETERS Message: Parameters provided for this request are invalid |
Security profile id or customer id from your access token, or the scope id from path parameters may be invalid for the List Data Query
Records request. Verify that the query was created for the scope id you've provided as path parameter. Verify that the access token is generated using the right customer's authorization code and your valid security profile credentials. |
ErrorResponse |
| 400 Bad Request |
Category: BAD_REQUEST Type: INVALID_MAX_RESULTS Message: Max results value is outside limits |
The request query parameter for maxResults has an invalid value.Verify that you’re using a maxResults value within defined limits. |
ErrorResponse |
| 400 Bad Request |
Category: BAD_REQUEST Type: INVALID_NEXT_PAGE Message: Invalid next page token |
The request query parameter for nextPageToken isn't valid. Verify that the token is correctly set, or remove it entirely to retrieve the first page again. |
ErrorResponse |
| 403 Forbidden |
Category: FORBIDDEN Type: ACCESS_DENIED Message: App is not authorized to do this operation |
Access token doesn't include required permissions for this operation, or is expired. Using the right customer's authorization code and your valid security profile credentials, verify that the access token is generated for the required scope id. If the customer didn't provide consent for the scope id, your Application can't request their data. If token is expired, generate a new valid token. |
ErrorResponse |
| 403 Forbidden |
Category: FORBIDDEN Type: MISSING_ACCESS_TOKEN Message: Access token not provided in request |
Access token hasn't been provided in the authorization header, is null, or empty. Add a valid access token in the authorization request header. |
ErrorResponse |
| 403 Forbidden |
Category: FORBIDDEN Type: APP_NOT_ALLOWLISTED Message: App is not allowlisted |
Your Application doesn't have permission to do this operation. Verify that your Data Portability allowlisting process is completed. |
ErrorResponse |
| 403 Forbidden |
Category: FORBIDDEN Type: SCOPE_NOT_ENABLED Message: Scope not enabled for app |
Scope isn't enabled for usage by your Application. Verify that your Data Portability allowlisting process is complete. If the error persists, sign in to your Amazon Developer account. Go to Contact Us. In the Category section, select "Amazon Data Portability". In the Topic section, select "Technical Issues". |
ErrorResponse |
| 403 Forbidden |
Category: FORBIDDEN Type: QUERY_NOT_COMPLETED Message: Query is not completed |
Query isn't complete. You can't perform List Data Query Records operation on a query that is in progress or canceled. Wait for the query to reach a final state, by monitoring the response notifications, before retrying your API request. If the query is canceled, your Application can't access the data. |
ErrorResponse |
| 403 Forbidden |
Category: FORBIDDEN Type: ACCESS_TIME_ELAPSED Message: Access time for this query has elapsed |
The period of time for requesting the data of this query has elapsed. Create a new query. |
ErrorResponse |
| 403 Forbidden |
Category: FORBIDDEN Type: APP_IDENTIFICATION_FAILURE Message: Failed to identify the app |
Your Application couldn't be identified. Verify that your Data Portability allowlisting process is completed, then retry your request. If the error persists, sign in to your Amazon Developer account. Go to Contact Us. In the Category section, select "Amazon Data Portability". In the Topic section, select "Technical Issues". |
ErrorResponse |
| 403 Forbidden |
Category: FORBIDDEN Type: MISSING_AUTHORIZATION_HEADER Message: Authorization header is missing or empty |
Authorization header is missing from your request, or is empty. Verify that your requests has a valid access token in authorization header. |
ErrorResponse |
| 403 Forbidden |
Category: FORBIDDEN Type: BLOCKED_REQUEST Message: Request blocked for security reasons |
Your request was blocked by security scanners. Retry the request. If the error persists, sign in to your Amazon Developer account. Go to Contact Us. In the Category section, select "Amazon Data Portability". In the Topic section, select "Technical Issues". |
ErrorResponse |
| 404 Not Found |
Category: RESOURCE_NOT_FOUND Type: SECURITY_PROFILE_NOT_FOUND Message: Security profile id does not exist |
The security profile from access token couldn’t be found. Verify that the access token is generated using valid credentials of your security profile created at onboarding. |
ErrorResponse |
| 404 Not Found |
Category: RESOURCE_NOT_FOUND Type: QUERY_ID_NOT_FOUND Message: Query id does not exist |
Query id provided as parameter couldn’t be found. Verify that the query id corresponds with the one returned by Create Data Query API. |
ErrorResponse |
| 404 Not Found |
Category: RESOURCE_NOT_FOUND Type: SCOPE_ID_NOT_FOUND Message: Scope id does not exist |
Scope id provided as parameter couldn’t be found. Review the Amazon Data Portability Scopes list and verify that the provided scope id is valid. |
ErrorResponse |
| 404 Not Found |
Category: RESOURCE_NOT_FOUND Type: RESOURCE_NOT_FOUND Message: Invalid URI or unsupported method |
Your request's URI is invalid or the REST method doesn't exist for this path. Review Data Portability API References verify that you're calling the right URI, and using the right REST method. |
ErrorResponse |
| 409 Conflict |
Category: CONFLICT Type: REQUEST_CONFLICT Message: There is a conflicting request in progress |
There is a conflicting request in progress for the same access token scope id and customer id. Validate that the request has the intended scope id and customer id. If not, adjust request as needed. Otherwise, wait for the existing request to reach a final state by monitoring the response notifications. |
ErrorResponse |
| 413 Content Too Large |
Category: CONTENT_TOO_LARGE Type: REQUEST_TOO_LARGE Message: Payload size limit exceeded |
Your request payload size exceeds the maximum value. Review Data Portability API References and verify that you provide only the required parameters with valid values. |
ErrorResponse |
| 429 Too Many Requests |
Category: TOO_MANY_REQUESTS Type: TOO_MANY_REQUESTS Message: Requests rate limit exceeded |
The request is throttled due to multiple requests in a given amount of time. Retry your request. |
ErrorResponse |
| 429 Too Many Requests |
Category: TOO_MANY_REQUESTS Type: QUOTA_EXCEEDED Message: Daily quota exceeded |
Your Application's daily quota for this scope was exceeded for this API. Review your requests' strategy and align it with the Amazon Data Portability API limits. |
ErrorResponse |
| 500 Internal Server Error |
Category: INTERNAL_SERVER_ERROR Type: MISSING_PARAMETER Message: Required parameter not provided in request |
One of the mandatory parameters from the API operation is missing. Review API parameters, update your request, and retry your request. If the error persists, sign in to your Amazon Developer account. Go to Contact Us. In the Category section, select "Amazon Data Portability". In the Topic section, select "Technical Issues". |
ErrorResponse |
| 500 Internal Server Error |
Category: INTERNAL_SERVER_ERROR Type: INTERNAL_SERVER_ERROR Message: Unexpected internal server exception |
An unexpected exception was encountered. Retry your request. If the error persists, sign in to your Amazon Developer account. Go to Contact Us. In the Category section, select "Amazon Data Portability". In the Topic section, select "Technical Issues". |
ErrorResponse |
| 500 Internal Server Error |
Category: INTERNAL_SERVER_ERROR Type: BLANK_SECURITY_PROFILE_ID Message: Security profile id is missing, empty or contains only whitespaces |
The security profile id provided through access token is missing, empty, or contains only whitespaces. Verify that the access token is generated using the security profile credentials of your Application, then retry your request. If the error persists, sign in to your Amazon Developer account. Go to Contact Us. In the Category section, select "Amazon Data Portability". In the Topic section, select "Technical Issues". |
ErrorResponse |
| 500 Internal Server Error |
Category: INTERNAL_SERVER_ERROR Type: INVALID_API_PATH Message: Invalid API path |
The provided API path isn't valid. Review Data Portability API References and verify that you use the right API path, then retry your request. If the error persists, sign in to your Amazon Developer account. Go to Contact Us. In the Category section, select "Amazon Data Portability". In the Topic section, select "Technical Issues". |
ErrorResponse |
| 500 Internal Server Error |
Category: INTERNAL_SERVER_ERROR Type: BLANK_SCOPE_ID Message: Scope id is missing, empty or contains only whitespaces |
The scopeId path parameter from the request is missing, empty, or contains only whitespaces. Verify that path of the request includes a valid scope id, then retry your request. If the error persists, sign in to your Amazon Developer account. Go to Contact Us. In the Category section, select "Amazon Data Portability". In the Topic section, select "Technical Issues". |
ErrorResponse |
| 500 Internal Server Error |
Category: INTERNAL_SERVER_ERROR Type: BLANK_CUSTOMER_ID Message: Customer id missing, empty or contains only whitespaces |
The Amazon customer id provided through access token is missing, empty, or contains only whitespaces. Verify that the access token is generated using the code returned in customer's authorization request, then retry your request. If the error persists, sign in to your Amazon Developer account. Go to Contact Us. In the Category section, select "Amazon Data Portability". In the Topic section, select "Technical Issues". |
ErrorResponse |
| 500 Internal Server Error |
Category: INTERNAL_SERVER_ERROR Type: BLANK_QUERY_ID Message: Query id is missing, empty or contains only whitespaces |
queryId path parameter is missing, empty or contains only whitespaces. Verify that you provide a query id in API path, then retry your request. If the error persists, sign in to your Amazon Developer account. Go to Contact Us. In the Category section, select "Amazon Data Portability". In the Topic section, select "Technical Issues". |
ErrorResponse |
| 500 Internal Server Error |
Category: INTERNAL_SERVER_ERROR Type: API_CONFIGURATION_ERROR Message: Failed to connect to server |
Encountered an internal API configuration error. Retry the request. If the error persists, sign in to your Amazon Developer account. Go to Contact Us. In the Category section, select "Amazon Data Portability". In the Topic section, select "Technical Issues". |
ErrorResponse |
| 500 Internal Server Error |
Category: INTERNAL_SERVER_ERROR Type: AUTHORIZATION_CONFIGURATION_ERROR Message: Failed to authenticate the app |
Failed to connect to authorizer. Retry the request. If the error persists, sign in to your Amazon Developer account. Go to Contact Us. In the Category section, select "Amazon Data Portability". In the Topic section, select "Technical Issues". |
ErrorResponse |
| 500 Internal Server Error |
Category: INTERNAL_SERVER_ERROR Type: AUTHORIZATION_FAILURE Message: Failed to authenticate the app |
Encountered error during Application authentication. Retry the request and ensure the authentication token is valid. If the error persists, sign in to your Amazon Developer account. Go to Contact Us. In the Category section, select "Amazon Data Portability". In the Topic section, select "Technical Issues". |
ErrorResponse |
| 500 Internal Server Error |
Category: INTERNAL_SERVER_ERROR Type: INTEGRATION_FAILURE Message: Failed to connect to server |
Encountered an internal server error. Retry the request. If the error persists, sign in to your Amazon Developer account. Go to Contact Us. In the Category section, select "Amazon Data Portability". In the Topic section, select "Technical Issues". |
ErrorResponse |
| 504 Gateway Timeout |
Category: GATEWAY_TIMEOUT Type: INTEGRATION_TIMEOUT Message: Request timed out |
Your request timed out. Retry the request. If the error persists, sign in to your Amazon Developer account. Go to Contact Us. In the Category section, select "Amazon Data Portability". In the Topic section, select "Technical Issues". |
ErrorResponse |
These are all known errors that can be returned. If you encounter an error not present in the table, start by retrying the error. If the error persists, sign in to your Amazon Developer account. Go to Contact Us. In the Category section, select "Amazon Data Portability". In the Topic section, select "Technical Issues".
Retrying errors:
By default, the API has no retry configuration added. If you received a response with 429, 500, or 504 HTTP status code, make a retry request. If you want to retry multiple times, we recommend that you implement an exponential backoff approach up to a defined limit, and then log the error and proceed with a manual follow-up and investigation. For example, time your retries in this time intervals: 1s, 2s, 4s, 10s, and 30s. The actual backoff times and limit depends on your business processes.
Definitions
CreateDataQueryOutput
The result of a create data query request.
| Name | Description | Schema |
|---|---|---|
| id required |
The queryId of the result specific to a customer and scope. |
UUID |
DataQueryRecord
A collection of data that indicates an entry with data for a customer query.
| Name | Description | Schema |
|---|---|---|
| schema required |
The S3 Presigned URLs to schema file that is available for download. | string |
| file required |
The S3 Presigned URLs to data file that is available for download. | string |
DataQueryStatus
A value that indicates the final status of the Create Query request.
Type: enum
| Value | Description |
|---|---|
| COMPLETED | Indicates that the query data has been successfully collected, and you can proceed to list records. |
| CANCELED | Indicates that the query data results aren't complete due to missing requirements. Possible causes: (1) The customer authorization has expired, (2) The customer has manually revoked the authorization, or (3) The customer account is on hold. |
ErrorResponse
Format for an error response.
| Name | Description | Schema |
|---|---|---|
| category required |
The category of an error. | string |
| type required |
The type of an error. | string |
| message required |
A message that describes the error condition. | string |
ListDataQueryRecordsOutput
The result of a create list query records.
| Name | Description | Schema |
|---|---|---|
| records required |
The records that matched the queryId. | <DataQueryRecord> array |
ResponseNotificationSubject
The subject of the notification response with the version number appended at the end. Fixed value.
Type: String
Value: Data Portability Notification 1.0
ResponseNotificationMessage
The message body of the notification response.
Type: String (JSON converted to String)
Structure specific for version 1.0:
| Name | Description | Schema |
|---|---|---|
| id required |
The queryId for which the notification has been sent. | string |
| version required |
Indicates the version Id for the response notification. | string |
| status required |
Indicates the status of the data query. | DataQueryStatus |
Release notes
| Version | Date | Changelist |
|---|---|---|
| 1.0 (current) | 2024-02-29 | Initial change |
Last updated: Oct 23, 2024