Skip to main content

Create a draft supporting document

Supporting Document Upload

Submitting a draft port request requires multiple supporting documents to be uploaded that provide details about the account associated with the telephone numbers and give our porting agents the authority to initiate the porting process from your current carrier to Telnyx.

The documents required for North American numbers are:

  1. The most recent bill copy/invoice from your current carrier
  2. A completed Letter of Authorization (LOA). This should be a completed copy of the LOA template

We recommend uploading these documents as either PDFs or images.

Uploading a supporting document is a multi-step process:

1. Submit an upload request through the API

This request signifies your intent to upload a document and will generate a temporary signature that grants you the ability to upload the file directly to Amazon S3 from either the browser or from your application server.

Specify the content type of the file being uploaded in the body of the request.


Example request body
"content_type": "image/jpeg"

The successful response will have status code 201 Created.

Example response body
"url": "",
"http_method": "POST",
"x-amz-signature": "a476e969385909bb91e8afd7718a1bfbb857e22204bf616ece59bbfefd5bf9fb",
"x-amz-date": "20171003T174526Z",
"x-amz-credential": "dummy/20171003/us-east-1/s3/aws4_request",
"x-amz-algorithm": "AWS4-HMAC-SHA256",
"policy": "eyJleHBpcmF0aW9uIjoiMjAxNy0xMC0wM1QxODo0NToyNloiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJmaWxlcy1zZXJ2aWNlLXN0YWdpbmcifSxbInN0YXJ0cy13aXRoIiwiJGtleSIsImRpcmVjdC11cGxvYWRzLzg3YTFlNTkxLWM1NGItNGYxYy04OTQ3LTZmODg4YWE5MTYwNi8iXSx7IngtYW16LWFsZ29yaXRobSI6IkFXUzQtSE1BQy1TSEEyNTYifSx7IngtYW16LWNyZWRlbnRpYWwiOiJBS0lBSkJOM0xLRlgzT1cyQ1BRQS8yMDE3MTAwMy91cy1lYXN0LTEvczMvYXdzNF9yZXF1ZXN0In0seyJ4LWFtei1kYXRlIjoiMjAxNzEwMDNUMTc0NTI2WiJ9LHsiY29udGVudC10eXBlIjoiaW1hZ2UvanBlZyJ9LHsiYWNsIjoicHVibGljLXJlYWQifV19",
"key": "direct-uploads/87a1e591-c54b-4f1c-8947-6f888aa91606/${filename}",
"content-type": "image/jpeg",
"acl": "public-read"
"file_form_field": "file"
2. Upload the file to Amazon S3 using a multipart file upload.


Example request

Each of the attributes in this request will need to be updated with the values received in the response to the upload request endpoint (see above) or, in the case of the file field, the path to the file you are uploading.

curl -X POST \ \
-H 'cache-control: no-cache' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F policy=eyJleHBpcmF0aW9uIjoiMjAxNy0xMC0wNFQxNjo0NToxOFoiLCJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJmaWxlcy1zZXJ2aWNlLXByb2QifSxbInN0YXJ0cy13aXRoIiwiJGtleSIsImRpcmVjdC11cGxvYWRzLzU1OTFkOTEwLTdlYTItNGE3NS05MGM5LWM0NjRmMzgwMzA1OS8iXSx7IngtYW16LWFsZ29yaXRobSI6IkFXUzQtSE1BQy1TSEEyNTYifSx7IngtYW16LWNyZWRlbnRpYWwiOiJBS0lBSkJOM0xLRlgzT1cyQ1BRQS8yMDE3MTAwNC91cy1lYXN0LTEvczMvYXdzNF9yZXF1ZXN0In0seyJ4LWFtei1kYXRlIjoiMjAxNzEwMDRUMTU0NTE4WiJ9LHsiY29udGVudC10eXBlIjoiaW1hZ2UvcG5nIn0seyJhY2wiOiJwdWJsaWMtcmVhZCJ9XX0= \
-F 'key=direct-uploads/5591d910-7ea2-4a75-90c9-c464f3803059/${filename}' \
-F x-amz-date=20171004T154518Z \
-F x-amz-signature=804b627293b29469b9cb93c17a7da91d2d24d57429d6e97d3b7b409b40010c45 \
-F x-amz-credential=dummy/20171004/us-east-1/s3/aws4_request \
-F content-type=image/png \
-F acl=public-read \
-F x-amz-algorithm=AWS4-HMAC-SHA256 \
-F file=@/path/to/file/image.png

The successful response will have status code 204 No Content. The information you need from the response is in the Location header.

Response headers

Location header example:


Save this value for the next step.

3. Associate the uploaded file with your draft sub request.

You can now associate the uploaded file with the draft sub request by making a request to the Telnyx API.


"document_type": "invoice",
"description": "",
"url": "{URL returned by S3 in the Location header}",
"draft_sub_request_id": "{draft_sub_request_id}"

Note: The document_type field should be set to either loa or invoice according to the type of document being uploaded.

The successful response will have status code 201 Created

These steps should be repeated for additional file uploads.


Path Parameters

    draft_port_request_id stringrequired

    Draft Port request id



Supporting document details

    description stringrequired

    Description of supporting document

    document_type stringrequired

    Possible values: [loa, csr, invoice, other]

    Type of document

    url stringrequired

    The AWS S3 url of the uploaded file

    draft_sub_request_id stringrequired

    The ID of the Draft Sub Request to associate the supporting document with


201: Supporting Document Response

401: Unauthorized