Amazon Data Portability API references
Amazon Data Portability lets you import customer data to your Application provided the customers give authorization.
Version information
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.
To ensure fair usage and system stability, the Create Data Query operation has the following rate limits per scope id:
Standard base rate: 5 requests per second
Burst limits: Up to 5 concurrent requests per second
Overall limit: No more than 20 requests within a 20-minute interval
Requests exceeding these limits will be throttled with a 429 HTTP status code.
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 a 403 Forbidden response with type ACCESS_DENIED when the access token isn't valid for the request. The message field identifies
the specific cause. See Error responses and schemas for all messages and how to resolve each one.
List Data Query Records
GET /{scopeId}/data-queries/{queryId}/records
Operation:
listDataQueryRecords
Description:
Use the listDataQueryRecords operation to view all customer data and transfer 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.
To ensure fair usage and system stability, the List Data Query operation has the following rate limits:
Standard base rate: 10 requests per second
Burst limits: Up to 5 concurrent requests per second
Daily quota: 100,000 requests
Requests exceeding these limits will be throttled and receive a 429 HTTP status code.
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 a 403 Forbidden response with type ACCESS_DENIED when the access token isn't valid for the request. The message field identifies
the specific cause. See Error responses and schemas for all messages and how to resolve each one.
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 and select the category that best matches your issue.
Provide the details related to your new HTTPS endpoints.
Responses:
The notification has the HTTP/HTTPS notification JSON format.
📘 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 and select the category that best matches your issue.
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: Access token is not authorized for this operation |
Access token doesn't include the required scope for this operation.
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. |
ErrorResponse |
403
Forbidden |
Category: FORBIDDEN
Type: ACCESS_DENIED
Message: Access token is expired. Refresh the token |
LWA access token in the authorization header has expired.
Generate a new access token using your refresh token, then retry the request.
See Step 2. Use the refresh token to get new tokens. |
ErrorResponse |
403
Forbidden |
Category: FORBIDDEN
Type: ACCESS_DENIED
Message: Access token has been revoked |
LWA access token is no longer valid and can't be used to authorize requests.
Request a new authorization from the customer, then generate a new access token. |
ErrorResponse |
403
Forbidden |
Category: FORBIDDEN
Type: ACCESS_DENIED
Message: Access token is invalid |
Access token in the authorization header is malformed or not recognized.
Verify that the authorization header contains a valid access token, then retry the request. |
ErrorResponse |
403
Forbidden |
Category: FORBIDDEN
Type: ACCESS_DENIED
Message: Access token format is invalid |
Authorization header is missing, empty, or isn't in the expected Bearer <token> format.
Verify that the authorization header is set to Bearer followed by a single space and a non-empty access token, then retry the request. |
ErrorResponse |
403
Forbidden |
Category: FORBIDDEN
Type: ACCESS_DENIED
Message: App is not authorized to do this operation |
Your Application isn't authorized to perform this operation.
Verify that the authorization header contains a valid access token generated for the required scope id. 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: 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 and select the category that best matches your issue. |
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 and select the category that best matches your issue.
|
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 and select the category that best matches your issue. |
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 |
429
Too Many Requests |
Category: THROTTLED
Type: TOO_MANY_REQUESTS
Message: Requests rate limit exceeded |
Your Application's rate limits 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 and select the category that best matches your issue. |
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 and select the category that best matches your issue. |
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 and select the category that best matches your issue.
|
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 and select the category that best matches your issue.
|
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 and select the category that best matches your issue.
|
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 and select the category that best matches your issue. |
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 and select the category that best matches your issue. |
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 and select the category that best matches your issue. |
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 and select the category that best matches your issue. |
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 and select the category that best matches your issue. |
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 and select the category that best matches your issue. |
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 and select the category that best matches your issue. |
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 and select the category that best matches your issue.
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: Apr 28, 2026
