Consola del desarrollador
Gracias por tu visita. Esta página solo está disponible en inglés.

Amazon Data Portability API references

Amazon Data Portability lets you import customer data to your Application provided the customers give authorization.

Version information

  • Version: 2024-02-29

License information

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

Operations

createDataQuery

listDataQueryRecords

📘 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
200 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: Sep 06, 2024