Menu
Amazon Pinpoint
REST API Reference

Import Jobs

Represents jobs that import endpoint definitions from an Amazon S3 bucket. You can use this resource to create import jobs, check the status of an in-progress import job, and access the history of your import jobs.

You can use an import job to create a segment by importing the endpoint definitions that belong to the segment. Creating segments with import jobs is useful if you have segments for your users outside of Amazon Pinpoint but you want to engage your users with Amazon Pinpoint campaigns.

URI

/v1/apps/application-id/jobs/import

HTTP Methods

GET

Returns information about your import jobs.

Header

Name Required Type

accept

false

string

Path

Name Required Type

application-id

true

string

Query

Name Required Type

page-size

false

string

token

false

string

Response

Status Code Schema

200

ImportJobsResponse

POST

Creates or updates an import job.

Body

Name Required Type

ImportJobRequest

true

ImportJobRequest

Header

Name Required Type

accept

false

string

Path

Name Required Type

application-id

true

string

Response

Status Code Schema

201

ImportJobResponse

Errors

Errors

Status Code Schema Error Type

400

MessageBody

BadRequestException

403

MessageBody

ForbiddenException

404

MessageBody

NotFoundException

405

MessageBody

MethodNotAllowedException

429

MessageBody

TooManyRequestsException

500

MessageBody

InternalServerErrorException

Schemas

Request Schemas

Example ImportJobRequest

{ "S3Url": "string", "RoleArn": "string", "ExternalId": "string", "Format": "CSV", "RegisterEndpoints": true, "DefineSegment": true, "SegmentName": "string", "SegmentId": "string" }

Response Schemas

Example ImportJobsResponse

{ "Item": [ { "ApplicationId": "string", "Id": "string", "JobStatus": "CREATED", "CompletedPieces": 0, "FailedPieces": 0, "TotalPieces": 0, "CreationDate": "string", "CompletionDate": "string", "Type": "string", "TotalFailures": 0, "TotalProcessed": 0, "Failures": [ "string" ], "Definition": { "S3Url": "string", "RoleArn": "string", "ExternalId": "string", "Format": "CSV", "RegisterEndpoints": true, "DefineSegment": true, "SegmentName": "string", "SegmentId": "string" } } ], "NextToken": "string" }

Example ImportJobResponse

{ "ApplicationId": "string", "Id": "string", "JobStatus": "CREATED", "CompletedPieces": 0, "FailedPieces": 0, "TotalPieces": 0, "CreationDate": "string", "CompletionDate": "string", "Type": "string", "TotalFailures": 0, "TotalProcessed": 0, "Failures": [ "string" ], "Definition": { "S3Url": "string", "RoleArn": "string", "ExternalId": "string", "Format": "CSV", "RegisterEndpoints": true, "DefineSegment": true, "SegmentName": "string", "SegmentId": "string" } }

Example MessageBody

{ "RequestID": "string", "Message": "string" }

Attributes

ImportJobRequest

Attribute Type Description

DefineSegment

boolean

Sets whether the endpoints create a segment when they are imported.

ExternalId

string

DEPRECATED. Your AWS account ID, which you assigned to the ExternalID key in an IAM trust policy. Used by Amazon Pinpoint to assume an IAM role. This requirement is removed, and external IDs are not recommended for IAM roles assumed by Amazon Pinpoint.

Format

string

The format of the files that contain the endpoint definitions. Valid values: CSV, JSON

RegisterEndpoints

boolean

Sets whether the endpoints are registered with Amazon Pinpoint when they are imported.

RoleArn

string

The Amazon Resource Name (ARN) of an IAM role that grants Amazon Pinpoint access to the Amazon S3 location that contains the endpoints to import.

S3Url

string

A URL that points to the location within an Amazon S3 bucket that contains the endpoints to import. The location can be a folder or a single file. The URL should follow this format: s3://bucket-name/folder-name/file-name

Amazon Pinpoint will import endpoints from this location and any subfolders it contains.

SegmentId

string

The ID of the segment to update if the import job is meant to update an existing segment.

SegmentName

string

A custom name for the segment created by the import job. Use if DefineSegment is true.

ImportJobsResponse

Attribute Type Description

Item

array

A list of import jobs for the application.

NextToken

string

The string that you use in a subsequent request to get the next page of results in a paginated response.

ImportJobResponse

Attribute Type Description

ApplicationId

string

The unique ID of the application to which the import job applies.

CompletedPieces

integer

The number of pieces that have successfully imported as of the time of the request.

CompletionDate

string

The date the import job completed in ISO 8601 format.

CreationDate

string

The date the import job was created in ISO 8601 format.

Definition

ImportJobResource

The import job settings.

FailedPieces

integer

The number of pieces that have failed to import as of the time of the request.

Failures

array

Provides up to 100 of the first failed entries for the job, if any exist.

Id

string

The unique ID of the import job.

JobStatus

string

The status of the import job. Valid values: CREATED, INITIALIZING, PROCESSING, COMPLETING, COMPLETED, FAILING, FAILED

The job status is FAILED if one or more pieces failed to import.

TotalFailures

integer

The number of endpoints that failed to import; for example, because of syntax errors.

TotalPieces

integer

The total number of pieces that must be imported to finish the job. Each piece is an approximately equal portion of the endpoints to import.

TotalProcessed

integer

The number of endpoints that were processed by the import job.

Type

string

The job type. Will be Import.

ImportJobResource

Attribute Type Description

DefineSegment

boolean

Sets whether the endpoints create a segment when they are imported.

ExternalId

string

DEPRECATED. Your AWS account ID, which you assigned to the ExternalID key in an IAM trust policy. Used by Amazon Pinpoint to assume an IAM role. This requirement is removed, and external IDs are not recommended for IAM roles assumed by Amazon Pinpoint.

Format

string

The format of the files that contain the endpoint definitions. Valid values: CSV, JSON

RegisterEndpoints

boolean

Sets whether the endpoints are registered with Amazon Pinpoint when they are imported.

RoleArn

string

The Amazon Resource Name (ARN) of an IAM role that grants Amazon Pinpoint access to the Amazon S3 location that contains the endpoints to import.

S3Url

string

A URL that points to the location within an Amazon S3 bucket that contains the endpoints to import. The location can be a folder or a single file. The URL should follow this format: s3://bucket-name/folder-name/file-name

Amazon Pinpoint will import endpoints from this location and any subfolders it contains.

SegmentId

string

The ID of the segment to update if the import job is meant to update an existing segment.

SegmentName

string

A custom name for the segment created by the import job. Use if DefineSegment is true.

MessageBody

Attribute Type Description

Message

string

The error message returned from the API.

RequestID

string

The unique message body ID.