Get Started

REST API: Pigeons

The Pigeon instance resource represents a single pigeon that you may ask Twilio to deploy to send a message. The Pigeons list resource represents the set of an account's pigeons. You can POST to this resource to add a new pigeon to your account.

To send messages to a destination via carrier pigeon see the Deploying Carrier Pigeons documentation.

Pigeon Instance Resource

Resource URI

/2010-04-01/Accounts/{AccountSid}/Pigeons/{PigeonSid}

Resource Properties

Property Description
Sid A 34 character string that uniquely identifies this pigeon.
DateCreated The date that this pigeon was added to your account, given in RFC 2822 format.
DateUpdated The date that this pigeon was last updated, given in RFC 2822 format.
FriendlyName A human readable descriptive name for this pigeon, up to 64 characters long. By default, the FriendlyName is the name of the pigeon given to it by the breeder.
AccountSid The unique id of the Account responsible for this pigeon.
Color The current paint color of this pigeon.
Uri The URI for this resource, relative to https://api.twilio.com.

HTTP GET

Example

  • GET /2010-04-01/Accounts/AC228ba.../Pigeons/PIe905d7e6b410746a0fb08c57e5a186f3 

    <TwilioResponse>
    <Pigeon>
        <Sid>PNe905d7e6b410746a0fb08c57e5a186f3</Sid>
        <AccountSid>AC228ba7a5fe4238be081ea6f3c44186f3</AccountSid>
        <FriendlyName>Ping Pong</FriendlyName>
        <Color>#ff0000</Color>
        <DateCreated>Fri, 1 Apr 2011 00:21:11 +0000</DateCreated>
        <DateUpdated>Fri, 1 Apr 2011 00:21:11 +0000</DateUpdated>
        <Uri>/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/Pigeons/PIe905d7e6b410746a0fb08c57e5a186f3</Uri>
    </Pigeon>
</TwilioResponse>

HTTP POST or PUT

Updates the pigeon, and returns the updated resource if successful.

Optional Parameters

There are a couple of fields that you may update:

Parameter Description
FriendlyName A human readable description for the pigeon, with maximum length of 64 characters. Defaults to the breeder's name for the pigeon.
Color The color you want Twilio to paint this pigeon, as a hexadecimal color code. This is #ff0000 (Twilio red) by default.
Example
POST /2010-04-01/Accounts/AC228ba.../Pigeons/PIe536d...

FriendlyName=Bo+Bo
Color=%23f45532

The response format is identical to the HTTP GET response documented above.

HTTP DELETE

Deletes the pigeon from the account. You will no longer be able to send messages with a pigeon after deleting him from an account. Returns an HTTP 204 response if successful, with no body.

Pigeons List Resource

Resource URI

/2010-04-01/Accounts/{AccountSid}/Pigeons

HTTP GET

Returns a list of Pigeon resource representations, each representing a pigeon ready for use by this account. The list includes paging information.

List Filters

The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive:

Parameter Description
Color Only return the pigeon resources that exactly match this color.
FriendlyName Only return the pigeon resource that exactly matches this name.
Example 1

Just grab the entire list of an account's pigeons.

  • GET /2010-04-01/Accounts/AC30947.../Pigeons 

    <TwilioResponse>
    <Pigeons page="0" numpages="1" pagesize="50" total="1" start="0" end="0" uri="/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/Pigeons" firstpageuri="/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/Pigeons?Page=0&amp;PageSize=50" previouspageuri="" nextpageuri="" lastpageuri="/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/Pigeons?Page=0&amp;PageSize=50">
        <Pigeon>
            <Sid>PIe905d7e6b410746a0fb08c57e5a186f3</Sid>
            <AccountSid>AC228ba7a5fe4238be081ea6f3c44186f3</AccountSid>
            <FriendlyName>Bo Bo</FriendlyName>
            <Color>>#f45532</Color>
            <DateCreated>Fri, 1 Apr 2011 00:21:11 +0000</DateCreated>
            <DateUpdated>Fri, 1 Apr 2011 00:21:11 +0000</DateUpdated>
            <Uri>/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/Pigeons/PIe905d7e6b410746a0fb08c57e5a186f3</Uri>
        </Pigeon>
        ...
    </Pigeons>
Example 2

Only show the pigeon records for pigeons with color #f45532.

GET /2010-04-01/Accounts/AC228ba.../Pigeons?Color=%23f45532

HTTP POST

Adds a new pigeon to your account. After making this request, Twilio will feed and paint your new pigeon and ready it for deployment. The following parameters are accepted:

Optional Parameters
Parameter Description
FriendlyName A human readable description for the pigeon with maximum length 64 characters. Defaults to the name of the pigeon as given by the breeder.
Color The color you'd like Twilio to paint the pigeon in hexadecimal format. If blank, this defaults to #ff0000 (Twilio red).
Example

Here is a typical request and response to provision a new pigeon:

  • POST /2010-04-01/Accounts/AC228ba.../Pigeons

    FriendlyName=Peter&Color=%23ba435b

    <TwilioResponse>
    <Pigeon>
        <Sid>PIe905d7e6b410746a0fb08c57e5a186f3</Sid>
        <AccountSid>AC228ba5e5fede1b49e100272a8640f438</AccountSid>
        <Color>#ba435b</Color>
        <FriendlyName>Peter</FriendlyName>
        <DateCreated>Fri, 1 Apr 2011 00:21:11 +0000</DateCreated>
        <DateUpdated>Fri, 1 Apr 2011 00:21:11 +0000</DateUpdated>
        <Uri>/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/Pigeons/PIe905d7e6b410746a0fb08c57e5a186f3</Uri>
    </Pigeon>
</TwilioResponse>

HTTP PUT

Not Supported.

HTTP DELETE

Not Supported.