NAV Navbar
shell
  • Introduction
  • Getting Started
  • Account
  • Addresses
  • Available Numbers
  • Calls
  • Contacts
  • Media
  • Numbers
  • Tags
  • Users
  • Webhooks
  • Introduction

    Welcome to the Parakeet API

    The Parakeet API Platform provides programmatic access to your Parakeet account that you can use to build custom integrations with your own applications.

    If you have any questions getting started with the API, or would like to see something else added here that we don't currently support, please contact us

    Getting Started

    Authentication

    Basic Authentication Header

    GET /api/v1/account HTTP/1.1
    Authorization: Basic aGVsbG86d29ybGQ=
    
    ...
    

    All requests to the Parakeet API require authentication.

    To authenticate, use HTTP basic authentication with the username set to your Account ID, and the password set to your API Key. You can access your API key at any time by visiting your Parakeet Dashboard (on the Integrations page).

    Rate Limiting

    Standard Rate Limit Headers

    HTTP/1.1 200 OK
    X-RateLimit-Remaining: 10
    X-RateLimit-Limit: 120
    X-RateLimit-Reset: 1505057280
    
    ...
    

    Exhausted Rate Limit Response

    HTTP/1.1 429 Too Many Requests
    X-RateLimit-Remaining: 0
    X-RateLimit-Limit: 120
    X-RateLimit-Reset: 1505057280
    Retry-After: 10
    
    ...
    

    In order to ensure high availability and quality service for all of our users, Parakeet enforces a limit of 120 requests every 60 seconds over the API. The limit is enforced independently per account.

    Each request will include the following headers

    Header Description
    X-RateLimit-Limit Maximum number of requests allowed per sampling window
    X-RateLimit-Remaining Remaining number of requests for the current time window
    X-RateLimit-Reset Timestamp when the current window rolls over

    Detecting Rate Limit

    If you exceed the rate limit, you will receive a 429 Too Many Requests response from the API. Additionally, a Retry-After header will be added indicating the number of seconds you must wait before you will be able to make another API call.

    Other Rate Limits

    Other endpoints in the Parakeet API may have specific rate limits that are more strict than the global rate limiter. For example, you may be rate limited when using the API to send text messages or provision phone numbers.

    Request Increased Limit

    If you have specific needs that require a higher limit, please contact us. We'd be happy to better understand your use case and increase your rate limit if it's appropriate.

    Date Formats

    The Parakeet API Platform always expresses all dates as ISO-8601 date strings (with milliseconds), and they are always provided in UTC. An example of a timestamp in the API is 2017-07-12T13:23:55.372Z.

    The only exception to this rule is the X-RateLimit-Reset header which, by convention, uses a Unix timestamp to indicate when rate limits are reset.

    Pagination

    Example Paginated Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    Link: <https://api.parakeet.is/api/v1/users?cursor=abcdefg>; rel="next"; cursor="abcdefg",
          <https://api.parakeet.is/api/v1/users?cursor=abcdefg>; rel="prev"; cursor="abcdefg",
    
    [ ... ]
    

    All list endpoints in Parakeet support cursor based pagination for scrolling through large data sets. Cursor pagination provides stable sorted collections of results with snapshot-like semantics.

    Links to next and previous pages of results are contained in the Link header of the HTTP reply. In addition to the complete URL, the header also separates out the parameter for the cursor, in case you would like to rebuild the URL yourself.

    Change Policy

    The Parakeet API Platform is always under active development. Documentation on this page is subject to change. We will always do our best to retain backwards compatibility for all changes, and notify our customers in the event a backwards incompatible change is made.

    Backwards compatible changes, however, may be made to the API with no advance notice. Your code should be able to handle these changes without issue. Specifically, we may add new fields to existing objects, new endpoints, and new webhook events without an announcement. By default, most languages and libraries will handle this without issue.

    Errors

    The Parakeet API follows HTTP conventions for indicating errors. Successful requests will yield a response code in the 200 range. Failed requests will generate a non-200 response code.

    Here are some of the status codes that the Parakeet API uses:

    Code Meaning
    400 Bad Request: Your request could not be understood, or is invalid
    401 Unauthorized: Your API key is invalid or was not included
    403 Forbidden: Your request was authenticated, but you do not have access to the requested resource
    404 Not Found: The requested resource could not be found
    405 Method Not Allowed: The endpoint you requested does not support your request method
    406 Not Acceptable: You requested a non-JSON response format
    422 Unprocessable Entity: Your request was syntactically valid, but logically invalid
    429 Too Many Requests: You have exceeded the rate limit for the API
    500 Internal Server Error: Something went wrong in our app, we've been notified

    Account

    Accounts in Parakeet are the top level item that contains all of your calls, users, teams, etc. Each API key grants access to a single account. You can use these endpoints to get information about the account that the API key belongs to.

    Account Object

    {
      "href": "/api/v1/account",
      "id": "AC5aca3cd9670511e78b0727a6bbabf621",
      "name": "Parakeet Communications, Inc.",
      "domain": "parakeet",
      "country": "US",
      "endpoint": "https://parakeet.parakeet.is",
      "sip_endpoint": "AC5aca3cd9670511e78b0727a6bbabf621.sip.dev.parakeet.is",
      "sip_domain": "AC5aca3cd9670511e78b0727a6bbabf621.sip.dev.parakeet.is",
      "sip_transport": "tls",
      "sip_port": 5061,
      "created_at": "2017-07-12T13:23:55.372Z",
      "updated_at": "2017-07-30T00:43:59.798Z"
    }
    
    Parameter Type Description
    id string Parakeet Account ID
    name string Display name for the account
    domain string Unique Parakeet domain for the account
    country string ISO-2 default country code for the account
    endpoint string URL to login to this account
    sip_endpoint string Endpoint that should be used for SIP connections
    sip_domain string Domain that should be used for SIP requests
    sip_transport string SIP transport mode (always TLS)
    sip_port number Port that should be used for connecting via SIP
    created_at date Timestamp that the account was created
    updated_at date Timestamp that the account was created

    View Account

    curl https://api.parakeet.is/api/v1/account
      -u '{accountId}:{apiKey}'
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "href": "/api/v1/account",
      "id": "AC5aca3cd9670511e78b0727a6bbabf621",
      "name": "Parakeet Communications, Inc.",
      "domain": "parakeet",
      "country": "US",
      "endpoint": "https://parakeet.parakeet.is",
      "sip_endpoint": "AC5aca3cd9670511e78b0727a6bbabf621.sip.dev.parakeet.is",
      "sip_domain": "AC5aca3cd9670511e78b0727a6bbabf621.sip.dev.parakeet.is",
      "sip_transport": "tls",
      "sip_port": 5061,
      "created_at": "2017-07-12T13:23:55.372Z",
      "updated_at": "2017-07-30T00:43:59.798Z"
    }
    

    Retrieve information about the current account.

    HTTP Request

    GET https://api.parakeet.is/api/v1/account

    Addresses

    Addresses are representations of your physical addresses that you may need to register with Parakeet. In some cases, governments require addresses to require a physical address. You'll know this is required when you see address_type of something other than none when using the Available Numbers API.

    Note that, by government regulation, Parakeet may share this address with local and state governments as part of the process of registering your phone number. If a phone number depends on an address being registered, you will not be able to delete that address.

    Address Object

    {
      "href": "/api/v1/addresses/ADd42adc1796f211e7a8d47328fce341c6",
      "id": "ADd42adc1796f211e7a8d47328fce341c6",
      "friendly_name": "New York Office",
      "name": "Parakeet Communications",
      "street": "16 W 22nd Street",
      "street2": null,
      "city": "New York",
      "region": "NY",
      "postal_code": "10010",
      "country_code": "US",
      "created_at": "2017-09-11T13:12:14.387Z",
      "updated_at": "2017-09-11T13:12:14.387Z"
    }
    
    Parameter Type Description
    id string Parakeet Address ID
    friendly_name string Friendly display name for this address (used for your records only)
    name string Personanl or company name associated with the address
    street string Primary street address
    city string City
    region string State, province, or local region name
    postal_code string ZIP code, postal code, or local equivalent
    country_code string ISO-2 country code
    created_at date Timestamp when the address was created
    updated_at date Timestamp when the address was last updated.

    Search Addresses

    curl https://api.parakeet.is/api/v1/addresses
      -u '{accountId}:{apiKey}'
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
      {
        "href": "/api/v1/addresses/ADd42adc1796f211e7a8d47328fce341c6",
        "id": "ADd42adc1796f211e7a8d47328fce341c6",
        "friendly_name": "New York Office",
        "name": "Parakeet Communications",
        "street": "16 W 22nd Street",
        "street2": null,
        "city": "New York",
        "region": "NY",
        "postal_code": "10010",
        "country_code": "US",
        "created_at": "2017-09-11T13:12:14.387Z",
        "updated_at": "2017-09-11T13:12:14.387Z"
      }
    ]
    

    Searches all registered addresses

    HTTP Request

    GET https://api.parakeet.is/api/v1/addresses

    Add Address

    curl https://api.parakeet.is/api/v1/addresses
      -H 'Content-Type: application/json'
      -u '{accountId}:{apiKey}'
      -d '{ 
        "friendly_name": "New York Office",
        "name": "Parakeet Communications",
        "street": "16 W 22nd Street",
        "city": "New York",
        "region": "NY",
        "postal_code": "10010",
        "country_code": "US"
      }'
    

    Example Response

    HTTP/1.1 201 Created
    Content-Type: application/json
    Location: https://api.parakeet.is/api/v1/addresses/ADd42adc1796f211e7a8d47328fce341c6
    
    {
      "href": "/api/v1/addresses/ADd42adc1796f211e7a8d47328fce341c6",
      "id": "ADd42adc1796f211e7a8d47328fce341c6",
      "friendly_name": "New York Office",
      "name": "Parakeet Communications",
      "street": "16 W 22nd Street",
      "street2": null,
      "city": "New York",
      "region": "NY",
      "postal_code": "10010",
      "country_code": "US",
      "created_at": "2017-09-11T13:12:14.387Z",
      "updated_at": "2017-09-11T13:12:14.387Z"
    }
    

    Provisions a new address on the Parakeet platform

    HTTP Request

    POST https://api.parakeet.is/api/v1/addresses

    Delete Address

    curl https://api.parakeet.is/api/v1/addresses/{id}
      -X DELETE
      -u '{accountId}:{apiKey}'
    }
    

    Example Response

    HTTP/1.1 204 No Content
    Content-Type: application/json
    

    Deletes a specific address by its identifier.

    HTTP Request

    DELETE https://api.parakeet.is/api/v1/addresses/{id}

    Available Numbers

    Available numbers are phone numbers that are ready for use in Parakeet. You can use the Parakeet API platform to search through available numbers and provision one for your account.

    Available Number Object

    {
      "id": "+12125551234",
      "number": "+12125551234",
      "country": "US",
      "type": "local",
      "address_requirement": "none"
    }
    
    Parameter Type Description
    id string E.164 Formatted Phone Number
    number string E.164 Formatted Phone Number
    country string ISO-2 country code for the number
    type string Type of number, one of local, mobile, or toll_free
    address_requirement string Physical address obligation, one of none, local, foreign, or any

    Search Available Numbers

    curl https://api.parakeet.is/api/v1/available_numbers
      -u '{accountId}:{apiKey}'
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
      {
        "id": "+12125551234",
        "number": "+12125551234",
        "country": "US",
        "type": "local",
        "address_requirement": "none"
      }
    ]
    

    Searches available phone numbers.

    Query Parameters

    Parameter Type Description
    country string ISO-2 country code to search for numbers
    type string Phone number type, one of local, mobile, or toll_free
    query string Filter for phone numbers containing an alphanumeric string

    HTTP Request

    GET https://api.parakeet.is/api/v1/available_numbers

    Calls

    In Parakeet, a Call object is a representation of an active call. Calls represent a single leg of a conversation. For example, if one Parakeet user places a call to another, two Call resources will be created. Each will have their own status, disposition, and perspective on the data.

    This understanding is critical to the way calls function in Parakeet.

    Call Object

    {
      "href": "/api/v1/calls/CA663b709f951611e787aae7b5749363bb",
      "id": "CA663b709f951611e787aae7b5749363bb",
      "direction": "inbound",
      "status": "completed",
      "disposition": "connected",
      "duration": 5,
      "remote": "+12125551234",
      "contact": { ... },
      "user": { ... },
      "assignee": { ... },
      "number": {
        "href": "/api/v1/numbers/PNb964a6be670811e7a538415bbbab7a13",
        "id": "PNb964a6be670811e7a538415bbbab7a13"
      },
      "comments": false,
      "archived": true,
      "tags": [],
      "started_at": "2017-09-09T04:21:49.626Z",
      "active_at": "2017-09-09T04:21:51.046Z",
      "ended_at": "2017-09-09T04:21:56.326Z",
      "created_at": "2017-09-09T04:21:49.507Z",
      "updated_at": "2017-09-09T04:21:56.398Z"
    }
    
    Parameter Type Description
    id string Parakeet Call ID
    direction string inbound if the call was received, outbound if it was placed
    status string Current status of the call
    disposition string Disposition of the call (null until status is completed)
    remote string Handle for the participant on the other end of the call
    contact Contact Contact on the other end of the call, or null if none was found
    user User User who spoke on the call, if known
    assignee User User the call is assigned to
    number Number Number that the call was made/received on
    started_at date Timestamp when the call started ringing
    active_at date Timestamp when the call went to an active status
    ended_at date Timestamp when the call was completed

    Search Calls

    curl https://api.parakeet.is/api/v1/calls
      -u '{accountId}:{apiKey}'
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    Link: <https://api.parakeet.is/api/v1/calls?cursor=abcdefg>; rel="next"; cursor="abcdefg"
    
    [
      {
        "href": "/api/v1/calls/CA663b709f951611e787aae7b5749363bb",
        "id": "CA663b709f951611e787aae7b5749363bb",
        "direction": "inbound",
        "status": "completed",
        "disposition": "connected",
        "duration": 5,
        "remote": "+12125551234",
        "contact": { ... },
        "user": { ... },
        "assignee": { ... },
        "number": {
          "href": "/api/v1/numbers/PNb964a6be670811e7a538415bbbab7a13",
          "id": "PNb964a6be670811e7a538415bbbab7a13"
        },
        "comments": false,
        "archived": true,
        "tags": [],
        "started_at": "2017-09-09T04:21:49.626Z",
        "active_at": "2017-09-09T04:21:51.046Z",
        "ended_at": "2017-09-09T04:21:56.326Z",
        "created_at": "2017-09-09T04:21:49.507Z",
        "updated_at": "2017-09-09T04:21:56.398Z"
      }
    ]
    

    Paginations through all of the call history on the given account. The returned list can be filtered and paginated using the standard Parakeet API practices.

    HTTP Request

    GET https://api.parakeet.is/api/v1/calls

    Query Parameters

    Parameter Type Values
    status string One of queued, ringing, in_progress, or completed
    disposition string One of connected, failed, canceled, busy, or no_answer
    assignee string Identifier for the user the call is assigned to
    archived boolean true for archived calls, false for unarchived
    tags string Name of a tag to search for
    limit number Number of results to return, max 100.

    Get Call

    curl https://api.parakeet.is/api/v1/calls/CA663b709f951611e787aae7b5749363bb
      -u '{accountId}:{apiKey}'
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "href": "/api/v1/calls/CA663b709f951611e787aae7b5749363bb",
      "id": "CA663b709f951611e787aae7b5749363bb",
      "direction": "inbound",
      "status": "completed",
      "disposition": "connected",
      "duration": 5,
      "remote": "+12125551234",
      "contact": { ... },
      "user": { ... },
      "assignee": { ... },
      "number": {
        "href": "/api/v1/numbers/PNb964a6be670811e7a538415bbbab7a13",
        "id": "PNb964a6be670811e7a538415bbbab7a13"
      },
      "comments": false,
      "archived": true,
      "tags": [],
      "started_at": "2017-09-09T04:21:49.626Z",
      "active_at": "2017-09-09T04:21:51.046Z",
      "ended_at": "2017-09-09T04:21:56.326Z",
      "created_at": "2017-09-09T04:21:49.507Z",
      "updated_at": "2017-09-09T04:21:56.398Z"
    }
    

    Fetch a specific call by its identifier. The returned type of this endpoint is the same as the search calls endpoint above.

    HTTP Request

    GET https://api.parakeet.is/api/v1/calls/{id}

    Update Call

    curl https://api.parakeet.is/api/v1/calls/CA663b709f951611e787aae7b5749363bb
      -H 'Content-Type: application/json'
      -u '{accountId}:{apiKey}'
      -d '{ "assignee": null }'
    

    Example Response

    {
      "href": "/api/v1/calls/CA663b709f951611e787aae7b5749363bb",
      "id": "CA663b709f951611e787aae7b5749363bb",
      "direction": "inbound",
      "status": "completed",
      "disposition": "connected",
      "duration": 5,
      "remote": "+12125551234",
      "contact": { ... },
      "user": { ... },
      "assignee": null,
      "number": {
        "href": "/api/v1/numbers/PNb964a6be670811e7a538415bbbab7a13",
        "id": "PNb964a6be670811e7a538415bbbab7a13"
      },
      "comments": false,
      "archived": true,
      "tags": [],
      "started_at": "2017-09-09T04:21:49.626Z",
      "active_at": "2017-09-09T04:21:51.046Z",
      "ended_at": "2017-09-09T04:21:56.326Z",
      "created_at": "2017-09-09T04:21:49.507Z",
      "updated_at": "2017-09-09T04:21:56.398Z"
    }
    

    Updates properties of an existing call. This endpoint can be used to reassign and archive calls.

    HTTP Request

    POST https://api.parakeet.is/api/v1/calls/{id}

    Request Body

    Parameter Type Values
    assignee string or object Either a User object or identifier
    archived boolean True to archive a call, false to unarchived

    Tag Call

    curl https://api.parakeet.is/api/v1/calls/CA663b709f951611e787aae7b5749363bb/tags
      -H 'Content-Type: application/json'
      -u '{accountId}:{apiKey}'
      -d '["Billing"]'
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
      {
        "name": "Billing",
        "color": "ff0000"
      }
    ]
    

    There are a few different endpoints for managing the tags associated with a call, depending on your needs. You can either add tags to the existing list, remove tags from the list, or replace the entire list with a new one.

    The content of each of these requests is the same: an array of strings indicating the tags that should be modified. Please see the examples for detail.

    Add Tags

    POST https://api.parakeet.is/api/v1/calls/{id}/tags

    Remove Tags

    DELETE https://api.parakeet.is/api/v1/calls/{id}/tags

    Replace Tags

    PUT https://api.parakeet.is/api/v1/calls/{id}/tags

    Comment on Call

    curl https://api.parakeet.is/api/v1/calls/CA663b709f951611e787aae7b5749363bb/comments
      -H 'Content-Type: application/json'
      -u '{accountId}:{apiKey}'
      -d '{ "content": "Hello World", "user": "US5ad75c3b670511e78b0727a6bbabf621" }'
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "content": "Hello World",
      "user": {
        "href": "/api/v1/users/US5ad75c3b670511e78b0727a6bbabf621",
        "id": "US5ad75c3b670511e78b0727a6bbabf621",
        "role": "owner",
        "email": "john@parakeet.is",
        "profile": {
          "first_name": "John",
          "last_name": "Smith",
          "role": "Owner",
          "time_zone": "America/New_York",
          "image": {
            "48": "https://static.parakeet.is/images/48.png",
            "64": "https://static.parakeet.is/images/64.png",
            "256": "https://static.parakeet.is/images/256.png",
            "512": "https://static.parakeet.is/images/512.png",
            "original": "https://static.parakeet.is/images/original.png"
          },
          "default_image": true
        },
        "schedule": {
          "href": "/api/v1/users/US5ad75c3b670511e78b0727a6bbabf621/schedule"
        },
        "created_at": "2017-07-12T13:23:55.463Z",
        "updated_at": "2017-07-27T01:13:16.138Z"
      },
      "created_at": "2017-07-12T13:23:55.463Z",
      "updated_at": "2017-07-27T01:13:16.138Z"
    }
    

    Similar to tags, comments on a call can be editing using the subresource endpoint. When using your API key to modify comments on a call, you must provide a user to associate the comments with.

    Add or Update Comments

    POST https://api.parakeet.is/api/v1/calls/{id}/comments

    Remove Comments

    DELETE https://api.parakeet.is/api/v1/calls/{id}/comments

    Contacts

    Contacts allow you to associate people and companies with phone numbers. When making or receiving calls in Parakeet, contacts will be automatically searched, giving you more valuable information than a simple phone number.

    Parakeet contacts can come from three different sources:

    While all contacts can be searched using the Parakeet API, only contacts created by the Parakeet apps can be managed by the API. Attempts to edit imported contacts, or managed contacts, will result in an uneditable_contact error.

    Contact Object

    {
      "href": "/api/v1/contacts/CNa402c39f726411e7a2d617b4f2b45fec",
      "id": "CNa402c39f726411e7a2d617b4f2b45fec",
      "title": null,
      "color": "862D0C",
      "display_name": "Jane Doe",
      "first_name": "Jane",
      "middle_name": null,
      "last_name": "Doe",
      "suffix": null,
      "nickname": null,
      "role": "Customer Service Manager",
      "company_name": "Parakeet",
      "default_image": true,
      "image": {
        "48": "https://static.parakeet.is/images/48.png",
        "64": "https://static.parakeet.is/images/64.png",
        "256": "https://static.parakeet.is/images/256.png",
        "512": "https://static.parakeet.is/images/512.png",
        "original": "https://static.parakeet.is/images/original.png"
      },
      "birth_date": null,
      "time_zone": null,
      "phone_numbers": [
        {
          "label": "Home",
          "country_code": "US",
          "number": "+12125551234",
          "primary": false
        }
      ],
      "emails": [],
      "addresses": [],
      "notes": null,
      "reference": null,
      "created_at": "2017-07-27T00:43:43.203Z",
      "updated_at": "2017-09-08T23:13:35.791Z"
    }
    
    Parameter Type Description
    id string Parakeet Contact ID
    title string Personal or professional title for the contact (Dr, Mr, Mrs, etc)
    color string Randomly generated color that can be used to create a default image
    display_name string Formatted name that should be displayed to the user
    first_name string First name of the contact
    middle_name string Middle name of the contact
    last_name string Last name of the contact
    suffix string Suffix for the contacts name
    nickname string Special nickname for the contact
    company_name string Name of the company that the contact belongs to
    default_image boolean true if the image object is a Parakeet generated default
    time_zone string Time zone that the contact is located in
    phone_numbers array Array of phone numbers attached to the contact
    emails array Array of email addresses attached to the contact
    addresses array Array of physical addresses attached to the contact
    birth_date string Birth date for the contact
    created_at date Timestamp when the contact was created
    updated_at date Timestamp when the contact was last updated

    Search Contacts

    HTTP/1.1 200 OK
    Content-Type: application/json
    Link: <https://api.parakeet.is/api/v1/contacts?cursor=abcdefg>; rel="next"; cursor="abcdefg"
    
    [
      {
        "href": "/api/v1/contacts/CNa402c39f726411e7a2d617b4f2b45fec",
        "id": "CNa402c39f726411e7a2d617b4f2b45fec",
        "title": null,
        "color": "862D0C",
        "display_name": "Jane Doe",
        "first_name": "Jane",
        "middle_name": null,
        "last_name": "Doe",
        "suffix": null,
        "nickname": null,
        "role": "Customer Service Manager",
        "company_name": "Parakeet",
        "default_image": true,
        "image": {
          "48": "https://static.parakeet.is/images/48.png",
          "64": "https://static.parakeet.is/images/64.png",
          "256": "https://static.parakeet.is/images/256.png",
          "512": "https://static.parakeet.is/images/512.png",
          "original": "https://static.parakeet.is/images/original.png"
        },
        "birth_date": null,
        "time_zone": null,
        "phone_numbers": [
          {
            "label": "Home",
            "country_code": "US",
            "number": "+12125551234",
            "primary": false
          }
        ],
        "emails": [],
        "addresses": [],
        "notes": null,
        "reference": null,
        "created_at": "2017-07-27T00:43:43.203Z",
        "updated_at": "2017-09-08T23:13:35.791Z"
      }
    ]
    

    Search the Parakeet contacts directly for contacts matching the query parameters.

    HTTP Request

    GET https://api.parakeet.is/api/v1/contacts

    Query Parameters

    Parameter Type Values
    query string Search contacts by name, title, company, etc
    sort string One of relevance, name
    handle string Search for contacts by an E.164 phone number
    limit number Number of results to return, max 100.

    Get Contact

    curl https://api.parakeet.is/api/v1/contacts/{id}
      -u '{accountId}:{apiKey}'
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "href": "/api/v1/contacts/CNa402c39f726411e7a2d617b4f2b45fec",
      "id": "CNa402c39f726411e7a2d617b4f2b45fec",
      "title": null,
      "color": "862D0C",
      "display_name": "Jane Doe",
      "first_name": "Jane",
      "middle_name": null,
      "last_name": "Doe",
      "suffix": null,
      "nickname": null,
      "role": "Customer Service Manager",
      "company_name": "Parakeet",
      "default_image": true,
      "image": {
        "48": "https://static.parakeet.is/images/48.png",
        "64": "https://static.parakeet.is/images/64.png",
        "256": "https://static.parakeet.is/images/256.png",
        "512": "https://static.parakeet.is/images/512.png",
        "original": "https://static.parakeet.is/images/original.png"
      },
      "birth_date": null,
      "time_zone": null,
      "phone_numbers": [
        {
          "label": "Home",
          "country_code": "US",
          "number": "+12125551234",
          "primary": false
        }
      ],
      "emails": [],
      "addresses": [],
      "notes": null,
      "reference": null,
      "created_at": "2017-07-27T00:43:43.203Z",
      "updated_at": "2017-09-08T23:13:35.791Z"
    }
    

    Fetches a specific contact by its identifier.

    HTTP Request

    GET https://api.parakeet.is/api/v1/contacts/{id}

    Create Contact

    curl https://api.parakeet.is/api/v1/contacts
      -X POST
      -u '{accountId}:{apiKey}'
      -H 'Content-Type: application/json'
      -d '{
        "first_name": "Jane",
        "last_name": "Doe",
        "phone_numbers": [{
          "label": "Mobile",
          "number": "+12125551234"
        }]
      }'
    

    Example Response

    HTTP/1.1 201 Created
    Content-Type: application/json
    Location: https://api.parakeet.is/api/v1/contacts/CNa402c39f726411e7a2d617b4f2b45fec
    
    {
      "href": "/api/v1/contacts/CNa402c39f726411e7a2d617b4f2b45fec",
      "id": "CNa402c39f726411e7a2d617b4f2b45fec",
      "title": null,
      "color": "862D0C",
      "display_name": "Jane Doe",
      "first_name": "Jane",
      "middle_name": null,
      "last_name": "Doe",
      "suffix": null,
      "nickname": null,
      "role": "Customer Service Manager",
      "company_name": "Parakeet",
      "default_image": true,
      "image": {
        "48": "https://static.parakeet.is/images/48.png",
        "64": "https://static.parakeet.is/images/64.png",
        "256": "https://static.parakeet.is/images/256.png",
        "512": "https://static.parakeet.is/images/512.png",
        "original": "https://static.parakeet.is/images/original.png"
      },
      "birth_date": null,
      "time_zone": null,
      "phone_numbers": [
        {
          "label": "Home",
          "country_code": "US",
          "number": "+12125551234",
          "primary": false
        }
      ],
      "emails": [],
      "addresses": [],
      "notes": null,
      "reference": null,
      "created_at": "2017-07-27T00:43:43.203Z",
      "updated_at": "2017-09-08T23:13:35.791Z"
    }
    

    Creates a new contact.

    HTTP Request

    POST https://api.parakeet.is/api/v1/contacts

    Update Contact

    curl https://api.parakeet.is/api/v1/contacts/{id}
      -X POST
      -u '{accountId}:{apiKey}'
      -H 'Content-Type: application/json'
      -d '{
        "first_name": "Jim",
        "last_name": "Doe",
      }'
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "href": "/api/v1/contacts/CNa402c39f726411e7a2d617b4f2b45fec",
      "id": "CNa402c39f726411e7a2d617b4f2b45fec",
      "title": null,
      "color": "862D0C",
      "display_name": "Jim Doe",
      "first_name": "Jim",
      "middle_name": null,
      "last_name": "Doe",
      "suffix": null,
      "nickname": null,
      "role": "Customer Service Manager",
      "company_name": "Parakeet",
      "default_image": true,
      "image": {
        "48": "https://static.parakeet.is/images/48.png",
        "64": "https://static.parakeet.is/images/64.png",
        "256": "https://static.parakeet.is/images/256.png",
        "512": "https://static.parakeet.is/images/512.png",
        "original": "https://static.parakeet.is/images/original.png"
      },
      "birth_date": null,
      "time_zone": null,
      "phone_numbers": [
        {
          "label": "Home",
          "country_code": "US",
          "number": "+12125551234",
          "primary": false
        }
      ],
      "emails": [],
      "addresses": [],
      "notes": null,
      "reference": null,
      "created_at": "2017-07-27T00:43:43.203Z",
      "updated_at": "2017-09-08T23:13:35.791Z"
    }
    

    Updates a specific contact by its identifier.

    HTTP Request

    POST https://api.parakeet.is/api/v1/contacts/{id}

    Media

    In Parakeet, media can be used as prompts and greetings played to callers as they contact your teams. You can upload and manage your media through the API.

    Media Object

    {
      "href": "/api/v1/media/MD9762a6db808511e7b97f892c90bd531f",
      "id": "MD9762a6db808511e7b97f892c90bd531f",
      "name": "IVR Greeting",
      "duration": 22,
      "url": "https://static.parakeet.is/media.mp3",
      "created_at": "2017-08-14T00:14:51.687Z",
      "updated_at": "2017-08-14T00:14:51.742Z"
    }
    
    Parameter Type Description
    id string Parakeet Media ID
    name string Name given to the media file when uplaoded
    duration number Duration of the media file in seconds
    url string Temporary URL to access the media file
    created_at date Timestamp when the media was uploaded
    updated_at date Timestamp when the media was last updated

    Search Media

    curl https://api.parakeet.is/api/v1/media
      -u '{accountId}:{apiKey}'
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    Link: <https://api.parakeet.is/api/v1/media?cursor=abcdefg>; rel="next"; cursor="abcdefg"
    
    [
      {
        "href": "/api/v1/media/MD57ea307d73c011e7a73fff738c977c1b",
        "id": "MD57ea307d73c011e7a73fff738c977c1b",
        "name": "IVR Greeting",
        "duration": 22,
        "url": "https://static.parakeet.is/media.mp3",
        "created_at": "2017-07-28T18:12:40.394Z",
        "updated_at": "2017-09-10T05:03:23.331Z"
      }
    ]
    

    Page through the Parakeet media in the account

    HTTP Request

    GET https://api.parakeet.is/api/v1/media

    Query Parameters

    Parameter Type Values
    limit number Number of results to return, max 100.

    Get Media

    curl https://api.parakeet.is/api/v1/media/{id}
      -u '{accountId}:{apiKey}'
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "href": "/api/v1/media/MD57ea307d73c011e7a73fff738c977c1b",
      "id": "MD57ea307d73c011e7a73fff738c977c1b",
      "name": "IVR Greeting",
      "duration": 22,
      "url": "https://static.parakeet.is/media.mp3",
      "created_at": "2017-07-28T18:12:40.394Z",
      "updated_at": "2017-09-10T05:03:23.331Z"
    }
    

    Fetches a specific media file by its identifier.

    HTTP Request

    GET https://api.parakeet.is/api/v1/media/{id}

    Delete Media

    curl https://api.parakeet.is/api/v1/media/{id}
      -X DELETE
      -H 'Content-Type: application/json'
      -u '{accountId}:{apiKey}'
    

    Example Response

    HTTP/1.1 204 No Content
    Content-Type: application/json
    

    Deletes an existing media file. The media file will be immediately deleted and any previously generated links will no longer be valid.

    Numbers

    Numbers are registered phone numbers under your Parakeet account that can be attached to users and teams. You can use the Parakeet API to provision new numbers, reassign numbers to a new destination, or delete numbers entirely.

    Number Object

    {
      "href": "/api/v1/numbers/PNb964a6be670811e7a538415bbbab7a13",
      "id": "PNb964a6be670811e7a538415bbbab7a13",
      "country_code": "US",
      "number": "+12673676170",
      "formatted_number": "(267) 367-6170",
      "status": "confirmed",
      "name": "Customer Service",
      "target_type": "team",
      "target": {
        "href": "/api/v1/teams/TM3a3586636b1911e7b0da9d1ed734b501",
        "id": "TM3a3586636b1911e7b0da9d1ed734b501"
      },
      "capabilities": [
        "voice",
        "mms",
        "sms"
      ],
      "created_at": "2017-07-12T13:48:02.585Z",
      "updated_at": "2017-08-21T20:19:12.856Z"
    }
    
    Parameter Type Description
    id string Parakeet Number ID
    country_code string ISO-2 country code for the phone number
    number string E.164 formatted phone number
    formatted_number string Phone number formatted to the country's national format
    status string Current status of the number, either porting or confirmed
    name string Name of the phone number for display, taken from the target
    target_type string Type of the target that this number points to
    target object Pointer to the object that this number routes to
    capabilities array Array of capabilities supported by this number, array of voice, sms, and mms
    created_at date Timestamp when the number was provisioned
    updated_at date Timestamp when the number was last updated

    Search Numbers

    curl https://api.parakeet.is/api/v1/numbers
      -u '{accountId}:{apiKey}'
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    Link: <https://api.parakeet.is/api/v1/numbers?cursor=abcdefg>; rel="next"; cursor="abcdefg"
    
    [
      {
        "href": "/api/v1/numbers/PNb964a6be670811e7a538415bbbab7a13",
        "id": "PNb964a6be670811e7a538415bbbab7a13",
        "country_code": "US",
        "number": "+12673676170",
        "formatted_number": "(267) 367-6170",
        "status": "confirmed",
        "name": "Customer Service",
        "target_type": "team",
        "target": {
          "href": "/api/v1/teams/TM3a3586636b1911e7b0da9d1ed734b501",
          "id": "TM3a3586636b1911e7b0da9d1ed734b501"
        },
        "capabilities": [
          "voice",
          "mms",
          "sms"
        ],
        "created_at": "2017-07-12T13:48:02.585Z",
        "updated_at": "2017-08-21T20:19:12.856Z"
      }
    ]
    

    Page through the Parakeet numbers in the account

    HTTP Request

    GET https://api.parakeet.is/api/v1/numbers

    Query Parameters

    Parameter Type Values
    limit number Number of results to return, max 100.

    Get Number

    curl https://api.parakeet.is/api/v1/numbers/{id}
      -u '{accountId}:{apiKey}'
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "href": "/api/v1/numbers/PNb964a6be670811e7a538415bbbab7a13",
      "id": "PNb964a6be670811e7a538415bbbab7a13",
      "country_code": "US",
      "number": "+12673676170",
      "formatted_number": "(267) 367-6170",
      "status": "confirmed",
      "name": "Customer Service",
      "target_type": "team",
      "target": {
        "href": "/api/v1/teams/TM3a3586636b1911e7b0da9d1ed734b501",
        "id": "TM3a3586636b1911e7b0da9d1ed734b501"
      },
      "capabilities": [
        "voice",
        "mms",
        "sms"
      ],
      "created_at": "2017-07-12T13:48:02.585Z",
      "updated_at": "2017-08-21T20:19:12.856Z"
    }
    

    Fetches a specific number by its identifier.

    HTTP Request

    GET https://api.parakeet.is/api/v1/numbers/{id}

    Delete Number

    curl https://api.parakeet.is/api/v1/numbers/{id}
      -X DELETE
      -H 'Content-Type: application/json'
      -u '{accountId}:{apiKey}'
    

    Example Response

    HTTP/1.1 204 No Content
    Content-Type: application/json
    

    Deletes an existing phone number. The number will be deleted immediately and released from your account. Once released, Parakeet may not be able to retrieve this number for you again.

    Provision Number

    curl https://api.parakeet.is/api/v1/numbers
      -X POST
      -H 'Content-Type: application/json'
      -u '{accountId}:{apiKey}'
      -d '{ "number": "+12125551234", "target": "TM3a3586636b1911e7b0da9d1ed734b501" }'
    

    Example Response

    HTTP/1.1 201 Created
    Content-Type: application/json
    Location: https://api.parakeet.is/api/v1/numbers/PNb964a6be670811e7a538415bbbab7a13
    
    {
      "href": "/api/v1/numbers/PNb964a6be670811e7a538415bbbab7a13",
      "id": "PNb964a6be670811e7a538415bbbab7a13",
      "country_code": "US",
      "number": "+12125551234",
      "formatted_number": "(212) 555-1234",
      "status": "confirmed",
      "name": "Customer Service",
      "target_type": "team",
      "target": {
        "href": "/api/v1/teams/TM3a3586636b1911e7b0da9d1ed734b501",
        "id": "TM3a3586636b1911e7b0da9d1ed734b501"
      },
      "capabilities": [
        "voice",
        "mms",
        "sms"
      ],
      "created_at": "2017-07-12T13:48:02.585Z",
      "updated_at": "2017-08-21T20:19:12.856Z"
    }
    

    Provisions a new phone number that was found using the Available Numbers API.

    Body

    Parameter Type Values
    number number Phone number returned from the Available Numbers API
    target string or object Pointer to a user or team that this number should route to

    Update Number

    curl https://api.parakeet.is/api/v1/numbers/PNb964a6be670811e7a538415bbbab7a13
      -X POST
      -H 'Content-Type: application/json'
      -u '{accountId}:{apiKey}'
      -d '{ "target": "TM3a3586636b1911e7b0da9d1ed734b501" }'
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "href": "/api/v1/numbers/PNb964a6be670811e7a538415bbbab7a13",
      "id": "PNb964a6be670811e7a538415bbbab7a13",
      "country_code": "US",
      "number": "+12125551234",
      "formatted_number": "(212) 555-1234",
      "status": "confirmed",
      "name": "Customer Service",
      "target_type": "team",
      "target": {
        "href": "/api/v1/teams/TM3a3586636b1911e7b0da9d1ed734b501",
        "id": "TM3a3586636b1911e7b0da9d1ed734b501"
      },
      "capabilities": [
        "voice",
        "mms",
        "sms"
      ],
      "created_at": "2017-07-12T13:48:02.585Z",
      "updated_at": "2017-08-21T20:19:12.856Z"
    }
    

    Updates a phone number and reassigns it to a new destination.

    Body

    Parameter Type Values
    target string or object Pointer to a user or team that this number should route to

    Tags

    Tags can help you keep your Parakeet activity organized by providing high level categorization for call and messaging activity. Through the Parakeet API, you can browse and manage your existing tags collection.

    Tag Object

    {
      "name": "Billing",
      "color": "ff0000"
    }
    
    Parameter Type Description
    name string Unique name for the tag
    color string Color that will be used for the tag

    Create Tag

    curl https://api.parakeet.is/api/v1/tags
      -H 'Content-Type: application/json'
      -u '{accountId}:{apiKey}'
      -d '{ "name": "Billing", "color": "ff0000" }'
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
      {
        "name": "Billing",
        "color": "ff0000"
      }
    ]
    

    Creates a new tag that can be used on calls.

    HTTP Request

    POST https://api.parakeet.is/api/v1/tags

    Update Tag

    curl https://api.parakeet.is/api/v1/tags/Billing
      -H 'Content-Type: application/json'
      -u '{accountId}:{apiKey}'
      -d '{ "color": "00ff00" }'
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
      {
        "name": "Billing",
        "color": "00ff00"
      }
    ]
    

    Updates an existing tag and allows you to update its color.

    HTTP Request

    POST https://api.parakeet.is/api/v1/tags/{name}

    Delete Tag

    curl https://api.parakeet.is/api/v1/tags/Billing
      -X DELETE
      -H 'Content-Type: application/json'
      -u '{accountId}:{apiKey}'
    

    Example Response

    HTTP/1.1 204 No Content
    Content-Type: application/json
    

    Deletes a tag, removing it from all calls and preventing it from being used in the future.

    HTTP Request

    DELETE https://api.parakeet.is/api/v1/tags/{name}

    Users

    Users are individual people that are able to make and receive calls under your Parakeet account. Using the Parakeet API, you can create, modify, and delete users on your account.

    User Object

    {
      "href": "/api/v1/users/US5ad75c3b670511e78b0727a6bbabf621",
      "id": "US5ad75c3b670511e78b0727a6bbabf621",
      "role": "owner",
      "email": "john@parakeet.is",
      "profile": {
        "first_name": "John",
        "last_name": "Smith",
        "role": "Owner",
        "time_zone": "America/New_York",
        "image": {
          "48": "https://static.parakeet.is/images/48.png",
          "64": "https://static.parakeet.is/images/64.png",
          "256": "https://static.parakeet.is/images/256.png",
          "512": "https://static.parakeet.is/images/512.png",
          "original": "https://static.parakeet.is/images/original.png"
        },
        "default_image": true
      },
      "schedule": {
        "href": "/api/v1/users/US5ad75c3b670511e78b0727a6bbabf621/schedule"
      },
      "created_at": "2017-07-12T13:23:55.463Z",
      "updated_at": "2017-07-27T01:13:16.138Z"
    }
    
    Parameter Type Description
    id string Parakeet User ID
    role string Set of permissions the user has user, admin or owner
    email string Email address associated with the user
    profile.first_name string First name for the user
    profile.last_name string Last name for the user
    created_at date Timestamp when the user was created
    updated_at date Timestamp when the user was last updated

    Search Users

    curl https://api.parakeet.is/api/v1/users
      -u '{accountId}:{apiKey}'
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    Link: <https://api.parakeet.is/api/v1/users?cursor=abcdefg>; rel="next"; cursor="abcdefg"
    
    [
      {
        "href": "/api/v1/users/US5ad75c3b670511e78b0727a6bbabf621",
        "id": "US5ad75c3b670511e78b0727a6bbabf621",
        "role": "owner",
        "email": "john@parakeet.is",
        "profile": {
          "first_name": "John",
          "last_name": "Smith",
          "role": "Owner",
          "time_zone": "America/New_York",
          "image": {
            "48": "https://static.parakeet.is/images/48.png",
            "64": "https://static.parakeet.is/images/64.png",
            "256": "https://static.parakeet.is/images/256.png",
            "512": "https://static.parakeet.is/images/512.png",
            "original": "https://static.parakeet.is/images/original.png"
          },
          "default_image": true
        },
        "schedule": {
          "href": "/api/v1/users/US5ad75c3b670511e78b0727a6bbabf621/schedule"
        },
        "created_at": "2017-07-12T13:23:55.463Z",
        "updated_at": "2017-07-27T01:13:16.138Z"
      }
    ]
    

    Page through the Parakeet users in the account

    HTTP Request

    GET https://api.parakeet.is/api/v1/users

    Query Parameters

    Parameter Type Values
    name string Search the users by name
    limit number Number of results to return, max 100.

    Get User

    curl https://api.parakeet.is/api/v1/users/{id}
      -u '{accountId}:{apiKey}'
    

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "href": "/api/v1/users/US5ad75c3b670511e78b0727a6bbabf621",
      "id": "US5ad75c3b670511e78b0727a6bbabf621",
      "role": "owner",
      "email": "john@parakeet.is",
      "profile": {
        "first_name": "John",
        "last_name": "Smith",
        "role": "Owner",
        "time_zone": "America/New_York",
        "image": {
          "48": "https://static.parakeet.is/images/48.png",
          "64": "https://static.parakeet.is/images/64.png",
          "256": "https://static.parakeet.is/images/256.png",
          "512": "https://static.parakeet.is/images/512.png",
          "original": "https://static.parakeet.is/images/original.png"
        },
        "default_image": true
      },
      "schedule": {
        "href": "/api/v1/users/US5ad75c3b670511e78b0727a6bbabf621/schedule"
      },
      "created_at": "2017-07-12T13:23:55.463Z",
      "updated_at": "2017-07-27T01:13:16.138Z"
    }
    

    Fetches a specific user by its identifier.

    HTTP Request

    GET https://api.parakeet.is/api/v1/users/{id}

    Create User

    curl https://api.parakeet.is/api/v1/users
      -H 'Content-Type: application/json'
      -u '{accountId}:{apiKey}'
      -d '{
        "email": "john.doe@company.com", 
        "profile": {
          "first_name": "John",
          "last_name": "Doe" 
        }
      }'
    

    Example Response

    HTTP/1.1 201 Created
    Content-Type: application/json
    Location: https://api.parakeet.is/api/v1/users/US5ad75c3b670511e78b0727a6bbabf621
    
    {
      "href": "/api/v1/users/US5ad75c3b670511e78b0727a6bbabf621",
      "id": "US5ad75c3b670511e78b0727a6bbabf621",
      "role": "owner",
      "email": "john@parakeet.is",
      "profile": {
        "first_name": "John",
        "last_name": "Smith",
        "role": "Owner",
        "time_zone": "America/New_York",
        "image": {
          "48": "https://static.parakeet.is/images/48.png",
          "64": "https://static.parakeet.is/images/64.png",
          "256": "https://static.parakeet.is/images/256.png",
          "512": "https://static.parakeet.is/images/512.png",
          "original": "https://static.parakeet.is/images/original.png"
        },
        "default_image": true
      },
      "schedule": {
        "href": "/api/v1/users/US5ad75c3b670511e78b0727a6bbabf621/schedule"
      },
      "created_at": "2017-07-12T13:23:55.463Z",
      "updated_at": "2017-07-27T01:13:16.138Z"
    }
    

    Creates a new Parakeet user. When a new user is created, Parakeet will automatically generate and send an invitation email that can be used to setup a password and start making calls.

    Webhooks

    Webhooks allow you to receive notifications in your own application when significant events occur in Parakeet. You can subscribe to a number of different events that allow you to hook into the Parakeet lifecycle in real time.

    Security

    HTTP/1.1 200 OK
    Content-Type: application/json
    X-Parakeet-Signature: 849facfb3849af8c748238fbca84723894fac
    
    {
      "type": "call.connected",
      "call": { ... }
    }
    

    In order to ensure requests are generated by Parakeet, we sign all outgoing webhooks with your primary API key. To generate the signature, we take a complete HMAC-SHA256 of the body contents, using your API key as the secret. The resulting value is hax encoded and placed in the X-Parakeet-Signature header.

    Retry Policy

    We get it, sometimes things don't go exactly as planned - it happens to us too. Don't worry, though. When things go wrong, we'll try your endpoint a few more times to see if it gets sorted out.

    If we don't receive a 200 response from your webhook, we'll retry after 100ms. Each time after that, we multiply the previous delay by 4, with a maximum of 10 minutes between requests. If, after 20 requests, things still haven't quite sorted out, we'll drop the message and move on.

    Please note, if we receive enough failed attempts to your webhook URL, it may be removed entirely.

    Supported Events

    Below is a complete list of events that are available via Parakeet webhooks. Parakeet creates a number of events that are not currently provided over webhooks, so if there's particular data you'd like to see here, please let us know.

    Event Description
    call.connected Call has been answered
    call.ended Call has terminated
    call.tagged Call has been tagged
    call.assigned Call has been assigned
    call.archived Call has been archived
    call.unarchived Call has been unarchived
    call.comment Call has been commented on
    call.voicemail Voicemail has been left for a call
    contact.created Contact has been created
    contact.updated Contact has been updated
    contact.deleted Contact has been deleted
    number.created Number has been provisioned and added
    number.updated Number has been updated to a new destination
    number.deleted Number has been deleted and is no longer callable
    user.created User has been added to the account
    user.updated User has been updated
    user.deleted User has been deleted from the account