Document APIs

The Document API allows you to upload, view, get, and download documents for use with other Phone Number APIs.

Some Phone Number APIs require documents, such as utility bills for the Port In API. Below are the types of documents you can upload with this API and where you can use them.

Twilio Process	Required document types	Description
Port In	Utility Bill	For a US port in request, a Utility Bill is required. The Utility Bill should be the most recent bill you have, within the last 30 days, that includes the account, owner/authorized user name, and address information for all the numbers you'd like to port.

Upload a Document

POST to https://numbers-upload.twilio.com/v1/Documents.

(warning)

Warning

This domain is different from the Phone Number APIs.

Request body parameters

Parameter	Required	Data Type	Description
`document_type`	Yes	String	Type of document to create. For the port in process, you should use the document type `utility_bill`.
`friendly_name`	No	String	The name to identify the document.
`File`	Yes	File	The document to upload. It should be an image or PDF document and should not be password protected. The maximum size allowed is 10MB.

Sample request

1curl -X POST 'https://numbers-upload.twilio.com/v1/Documents' \
2--data-urlencode 'friendly_name="Your document name"' \
3--data-urlencode 'File=@"/Users/your_user/Documents/doc.pdf"' \
4--data-urlencode 'document_type="utility_bill"'

Response

The API responds with the following properties. Be sure to keep track of the SID returned, as this is the unique identifier for the document to use in the port in request. Please review that the mime_type is not empty; an empty mime_type means the uploaded document has no content.

Parameter	Data Type	Description
`sid`	String	Document SID. This is the Document's identifier.
`account_sid`	String	Document owner's account.
`document_type`	String	Document type.
`version`	Number	Document version.
`status`	String	The current status of a Document. Can be one of: `DRAFT`, `PENDING_REVIEW`, `REJECTED`, `APPROVED`, `EXPIRED`.
`date_created`	Date	Date the document was created.
`date_updated`	Date	The date the Document was most recently updated.
`friendly_name`	String	Name of the document.
`mime_type`	String	File type (`image` or `pdf`).
`failure_reason`	String	Reason why the process failed, if an error occurred.
`created_by`	String	Account SID for the user who created the Document.

Below are example response bodies.

Response to a successful request

HTTP Status Code	Next Steps
`201`	File was successfully created. You can use this Document with other Phone Numbers APIs.

1{
2    "sid": "RDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa01",
3    "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa01",
4    "document_type": "utility_bill",
5    "version": 1,
6    "status": "DRAFT",
7    "date_created": "2023-11-02T19:21:32Z",
8    "date_updated": "2023-11-02T19:21:32Z",
9    "friendly_name": "Utility Bill",
10    "mime_type": "application/pdf",
11    "failure_reason": null,
12    "created_by": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa01",
13    "reviewer": null,
14    "attributes": [
15        {
16            "name": "address_sids",
17            "value": null
18        }
19    ]
20}

Response to a failed request

HTTP Status Code	Next Steps
`400`	A value in the request was invalid or missing. Please review the request and the error codes returned. Correct any mistakes and try resubmitting the request.

(information)

Info

Check the mime_type field in the response. If it is empty, the document was not uploaded correctly or it does not have content.

1{
2    "message": "Document type not found",
3    "code": 70002,
4    "user_error": true,
5    "http_status_code": 400,
6    "params": {}
7}