NAV Navbar
shell
  • Introduction
  • Rate Limiting
  • Authentication
  • People
  • Groups
  • Errors
  • Introduction

    Welcome to Text In Church's API! You can use this API to access all our API endpoints, such as the Person API to look up or create people, or the Groups API to create a new group.

    The API is organized around REST. All requests should be made over SSL. All request and response bodies, including errors, are encoded in JSON.

    Rate Limiting

    Usually the API is rate limited to 100 requests per 20 seconds per access token, but that limit and time period are subject to change either up or down as necessary. If you think your app may be affected by rate limits, it should be developed to adjust dynamically inspecting the values of X-TIC-API-Request-Rate-Limit and X-TIC-API-Request-Rate-Period in the HTTP headers. Your current count is discoverable in the X-TIC-API-Request-Rate-Count key. Requests that exceed the current limit will return an HTTP status 429. The number of seconds to wait until you can retry those requests is in the key Retry-After.

    Authentication

    Authentication to the Text In Church API requires the use of OAuth version 2.0.

    Visit textinchurch.com/developer/applications to create an OAuth application token.

    Example of sending the POST request using curl:

    curl -X POST https://api.textinchurch.com/oauth/token \
         -F grant_type=authorization_code \
         -F code=1234567890 \
         -F client_id=2345678901 \
         -F client_secret=3456789012 \
         -F redirect_uri=https://mywebsite.com/auth/complete
    

    Sample response containing the access token:

    {
      "access_token": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "token_type": "bearer",
      "expires_in": 7200,
      "refresh_token": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "scope": "people",
      "created_at": 1469553476
    }
    

    Pass the access token in all subsequent API requests:

    curl -H 'Authorization: Bearer 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' https://api.textinchurch.com/people
    

    Make sure your app conforms to the OAuth 2.0 specification. Generally, to authenticate a user, follow these steps:

    1. Redirect the user's browser to https://api.textinchurch.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=https://mywebsite.com/auth/complete&response_type=code&scope=people (replace CLIENT_ID and https://mywebsite.com/auth/complete with your actual redirect URI).

      If you need different scope, replace scope=people appropriately (see "Scopes" section below).

    2. Text In Church will redirect the user's browser back to the given redirect URI with a code param.

    3. Send a POST request in the background to https://api.textinchurch.com/oauth/token with the following params: {"grant_type": "authorization_code", "code": "CODE_FROM_STEP_2", "client_id": "CLIENT_ID", "client_secret": "CLIENT_SECRET", "redirect_uri": "https://mywebsite.com/auth/complete"} (replace CLIENT_ID, CLIENT_SECRET, CODE_FROM_STEP_2, and the redirect URI appropriately).

    4. The response you get back will contain the access token and other information.

    5. Use the access token for all API requests by passing it in the Authorization header, using the Bearer authentication scheme.

    OAuth access tokens expire after 2 hours from the time they are issued, but we also provide a refresh token you can use to get a new access token at any time, even after the access token expires, without forcing the user to re-authorize.

    We will honor refresh tokens for up to 1 year after the date its associated access token was issued. This means that, if your app does not issue a refresh for 1 year, then your user will need to re-authorize.

    Scopes

    Each Text In Church app is a distinct OAuth scope.

    App Scope
    Groups groups
    People people

    Authorization URL is https://api.textinchurch.com/oauth/authorize Token URL is https://api.textinchurch.com/oauth/token When authorizing, you can request scopes using the scope parameter. The value should be a space-separated list of scopes. The value for response_type should be code

    People

    Get All People

    curl -v -u token:secret "https://api.textinchurch.com/people"
    

    The above command returns JSON structured like this:

    [
      {
        "id": 1,
        "first_name": "Marianne",
        "last_name": "Bagley",
        "email":"MarianneBBagley@rhyta.com",
        "phone":"620-225-4989",
        "address_1":"1866 Roosevelt Road",
        "address_2":"",
        "city":"Dodge City",
        "state":"KS",
        "zip":"67801"
      },
      {
        "id": 2,
        "first_name": "Alfonso",
        "last_name": "Larry",
        "email":"AlfonsoLLarry@jourrapide.com",
        "phone":"805-764-0954",
        "address_1":"4316 Par Drive",
        "address_2":"",
        "city":"Pomona",
        "state":"CA",
        "zip":"91766"
      }
    ]
    

    This endpoint retrieves all people.

    HTTP Request

    GET https://api.textinchurch.com/people

    Query Parameters

    Parameter Value Description
    where[first_name] string query on a specific first name
    where[last_name] string query on a specific last name
    where[email] string query on a specific email
    where[phone] string query on a specific mobile phone number
    per_page 25 how many records to return per page (min=1, max=100, default=25)
    offset 0 get results from given start
    order first_name prefix with a hyphen (-first_name) to reverse the order
    order last_name prefix with a hyphen (-last_name) to reverse the order
    order created_at prefix with a hyphen (-created_at) to reverse the order

    Get a Specific Person

    curl -v -u token:secret "https://api.textinchurch.com/people/2"
    

    The above command returns JSON structured like this:

    {
      "id": 2,
      "first_name": "Alfonso",
      "last_name": "Larry",
      "email":"AlfonsoLLarry@jourrapide.com",
      "phone":"805-764-0954",
      "address_1":"4316 Par Drive",
      "address_2":"",
      "city":"Pomona",
      "state":"CA",
      "zip":"91766"
    }
    

    This endpoint retrieves a specific person.

    HTTP Request

    GET https://api.textinchurch.com/people/<ID>

    URL Parameters

    Parameter Description
    ID The ID of the person to retrieve

    Create a New Person

    curl -v -u token:secret -X POST -d
    '{"data":{"data":{...}}}' "https://api.textinchurch.com/people"
    

    This endpoint creates a new person.

    HTTP Request

    POST https://api.textinchurch.com/people

    URL Parameters

    Parameter Type Notes
    first_name string
    last_name string
    email string
    phone string
    address string
    address_2 string
    city string
    state string 2 character abbreviation
    zip string

    Groups

    Get All Groups

    curl -v -u token:secret  "https://api.textinchurch.com/groups"
    

    The above command returns JSON structured like this:

    [
      {
        "id": 1,
        "name": "My Super Group",
        "comments": "This is a longer description of the group's purpose.",
      },
      {
        "id": 2,
        "name": "Another Awesome Group",
        "comments": "Just more details about how great this group is.",
      }
    ]
    

    This endpoint retrieves all groups.

    HTTP Request

    GET https://api.textinchurch.com/groups

    Query Parameters

    Parameter Value Description
    where[group_name] string query on a specific group name
    per_page 25 how many records to return per page (min=1, max=100, default=25)
    offset 0 get results from given start
    order group_name prefix with a hyphen (-group_name) to reverse the order
    order updated_at prefix with a hyphen (-updated_at) to reverse the order

    Get a Specific Group

    curl -v -u token:secret  "https://api.textinchurch.com/groups/2"
    

    The above command returns JSON structured like this:

    {
      "id": 2,
      "name": "Another Awesome Group",
      "comments": "Just more details about how great this group is.",
    }
    

    This endpoint retrieves a specific group.

    HTTP Request

    GET https://api.textinchurch.com/groups/<ID>

    URL Parameters

    Parameter Description
    ID The ID of the group to retrieve

    Create a New Group

    curl -v -u token:secret -X POST -d
    '{"data":{"data":{...}}}' "https://api.textinchurch.com/groups"
    

    This endpoint creates a new group.

    HTTP Request

    POST https://api.textinchurch.com/groups

    URL Parameters

    Parameter Type
    name string
    comments string

    Errors

    The Text In Church API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request is invalid.
    401 Unauthorized -- Your API key is wrong.
    403 Forbidden -- The resource requested is hidden for administrators only.
    404 Not Found -- The specified resource could not be found.
    429 Too Many Requests -- You're request has exceeded the rate limit.
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.