Pathable Developer API

The Pathable Developer API provides read and write access to your Pathable communities and events. The API is currently in BETA and your suggestions will be greatly appreciated. For questions and suggestion please email support@pathable.com or your account manager. Enjoy!

To acquire an API token for testing and/or production purposes, please contact info@pathable.com.

Base

Pathable organizes users and their content such as meetings, documents, and group membership into communities. Typically these communities represent your events. You can request data across all your communities or scope your requests to a specific community by choosing one of two URL base end-point forms. Simply combine any of the base forms with the specific API end-points to frame what data you wish to retrieve or manipulate.

Base End Points

http://api.pathable.com/v1/

http://api.pathable.com/v1/communities/<community ID>/

Authorization

api_token Your unique developer API token provided as a HTTP query parameter. All requests must include either this api_token or the HTTP header api-token.
Api-Token Your unique developer API token provided in the HTTP request header. All requests must include either this api-token or the HTTP get api_token.
auth_token An required user authentication token. This token is used to establish an authorized session for a specific user, causing any request that includes it to behave as if the user successfully logged in for that request. Many requests require an authorized user with admin privileges on the community.

Examples:

Using a request header:

curl -H "Api-Token: 3d98d63c-ef88-4dc6-a5d5-068ffc8bf6ae" -X GET http://api.pathable.com/v1/users.json -v

Using a query parameter:

curl -X GET http://api.pathable.com/v1/users.json?api_token=3d98d63c-ef88-4dc6-a5d5-068ffc8bf6ae -v

Scoping results to a specific community:

curl -X GET http://api.pathable.com/v1/communities/123/users.json?api_token=3d98d63c-ef88-4dc6-a5d5-068ffc8bf6ae -v

Authorizing as a specific user:

curl -H "Api-Token: 3d98d63c-ef88-4dc6-a5d5-068ffc8bf6ae" -X GET http://api.pathable.com/v1/users.json?auth_token=23423k32jk23 -v

GET Parameters

Community Scope

All requests can be scoped to a specific community, usually an event. By default all requests are scoped to the umbrella community (or association) and include all objects (users, meetings, groups, etc.) across all communities or events. For example, the authentication_url on user responses will direct the user to the community context if provided, otherwise to the association context.

community_id Specify a community context to which requests should be scoped.

List Parameters

Most requests for lists of things accept pagination and search parameters. You can increase the total number of entries returned per request (per page) but if your requests get too large, you may receive timeout errors. Please be sure to paginate your results with enough buffer to avoid requesting result sets that take too long to return.

per_page Specify how many results to return per request.
page Specify which page of results to return.
sort_mode Specify in which direction results should be sorted. Allowed options are ‘asc’ and ‘desc’.
order Specify by which attribute results should be sorted. For example: ‘updated_at’ or ‘first_name’.
with Specify by which attribute results should be filtered. Supports ranged queries.
conditions Specify attribute conditions on which to search. Listed conditions for a particular end-point are ALL searched when the general “query” parameter is used. Cannot be used in ranges.

Default Response

Responses can be returned as JSON or XML specified by the content type in the request.
Response information for lists of things includes pagination details and counts. The results are always listed under the “results” key. Instance results are always returned in the document root.

{
  "total_entries": 100,
  "total_pages": 10,
  "per_page": 10,
  "current_page": 1,
  "results": {...}
}

Errors

Errors are always returned using standard HTTP error codes.

401 Unauthorized The request has failed due to an authorization error. This could be because the API token provided is invalid or because the user authorized via the auth_token does not have sufficient permissions for the requested end-point and request method.
422 Unprocessable Entity The request was well-formed but failed because of incorrect instance information. This typically occurs when the provided data is invalid or not unique. Detailed validation failure information will be included in the response body.

POST/PUT Parameters

General

When creating or updating data you can POST or PUT data either as HTTP parameters or as JSON. When providing JSON data the request must be valid JSON and the content type must be set to “application/json.”

Examples:

Data provided as HTTP parameters creating a user with an email and a first name:

curl -H "Api-Token: 3d98d63c-ef88-4dc6-a5d5-068ffc8bf6ae" --data "email=email@domain.com&first_name=Peter" -X POST http://api.pathable.com/v1/session.json -v

Data provided as JSON creating a user with an email and a first name:

curl -H "Api-Token: 3d98d63c-ef88-4dc6-a5d5-068ffc8bf6ae" -H "Content-Type: application/json" -H "Accepts: application/json" -d "{'primary_email': 'test1@test.com', 'first_name': 'Peter', 'auth_token': '62bc8fRzYofQfu9VcqUT'}" -X POST http://api.pathable.com/v1/session.json -v

Sessions

You can authorize a user using their email and password. If successful the response will include the full user object which includes the users “auth_token”, which can be used to scope certain requests to the authorized user. Use this to manage login sessions on behalf of users. Note that you can also retrieve the “auth_token” (and other details) on any user when authenticated as an administrator. Use this approach when users do not need to provide their own credentials.

See the Single Sign-on How-to for more details.

End point

/sessions.json

Request Methods:

CREATE

Parameters:

email An email address to look up a user.
password A password to used to authenticate a user.
primary_email The users primary email address.
string
external_id The users custom external ID. This can be provided by you or will otherwise be randomly generated.
string
ID The unique Pathable user ID.
integer

Examples:

“Sign in” as an attendee by providing his/her email and password. The response “auth_token” allows future requests to be scoped to this user, ensuring correct permissions, access limitations, and data scoping.

curl -H "Api-Token: 3d98d63c-ef88-4dc6-a5d5-068ffc8bf6ae" -d "email=email@domain.com&password=password" -X POST http://api.pathable.com/v1/session.json -v

Retrieve the authentication URL for a user by ID:

curl "http://api.pathable.com/v1/communities/292/users/201/session.json?api_token=83f7425d-a352-4e1e-8bb6-709d29438438&auth_token=lXvFIWzYsjPlGtOrEVuM" -v

Retrieve the authentication URL for a user by email:

curl "http://api.pathable.com/v1/communities/292/session.json?api_token=83f7425d-a352-4e1e-8bb6-709d29438438&auth_token=lXvFIWzYsjPlGtOrEVuM&primary_email=email@address.com" -v

Retrieve the authentication URL for a user by custom external ID:

curl "http://api.pathable.com/v1/communities/292/session.json?api_token=83f7425d-a352-4e1e-8bb6-709d29438438&auth_token=lXvFIWzYsjPlGtOrEVuM&external_id=asdja9dfas-asdfasdlkjasd9-asdf3dsdf" -v

Response:

{
    "authentication_token": "huiWJCtrixTstv0XLcTt", 
    "authentication_url": "http://greencon2012.gc.pathable.com/session?auth_token=xxeJCtrixTstv0XLcTt", 
    "class_name": "User", 
    "created_at": 1316552385000, 
    "dirty": true, 
    "external_id": "ca350569-2406-4eb3-a2cd-54631e8b6a6f", 
    "id": 208, 
    "primary_email": "peter@pathable.com", 
    "updated_at": 1349461881000, 
    "visible": true
}

Users

Community users (i.e. the people attending events or association members) can be created, retrieved and destroyed. By default, the 20 most recently updated users will be returned. The number per page as well as page number can be specified on GET requests. Note that if you request too many users at once and receive a timeout you’ll need to reduce the page size and manage the retrieval of users in batches. Users can be created, updated and destroyed using POST, PUT, and DELETE respectively. Note that some requests require authorization.

End points

/users.json
/users/<id>.json

Request Methods:

GET
POST
PUT
DELETE

with[visible] Find visible or invisible users.
boolean
conditions[first_name] Find users with a matching first name.
string
conditions[last_name] Find users with a matching last name.
string
conditions[email] Find users with a matching email address.
string
conditions[organization_name] Find users with a matching organization name.
string
conditions[title] Find users with a matching title.
string
conditions[tags] Find users associated with tags which have matching names.
string
conditions[interests] Find users associated with interests which have matching names.
string
conditions[categories] Find users associated with categories which have matching names.
string
conditions[meetings] Find users associated with meetings which have matching names.
string
conditions[groups] Find users associated with tags, categories, interests, or meetings with matching names.
string

User Attributes:

You can create or update users using any of the following attributes. Attributes are posted as HTTP parameters, as JSON in PUT and POST requests, or via the XML Polling API. Any attributes not listed here are simply ignored.

primary_email The users primary email address. Only displayed publicly if the “Display email addresses on profiles” option is checked.
string
first_name The users first name. Can include a middle name or initial.
string
last_name The users last name.
string
credentials The users professional credentials, for example PhD or LMP.
string
title The users business/professional title, for example CTO or Senior Account Executive.
string
organization_name The users company or organization name.
string
address The users physical address, parts separated by newlines. Only displayed publicly if the “Display addresses on profiles” option is checked.
string
phone_number The users telephone number. Only displayed publicly if the “Display phone numbers on profiles” option is checked.
string
bio The users professional bio or “about me” statement. Any valid markdown formatting will automatically be rendered into the attribute rendered_bio. < and > will be HTML encoded. Links will automatically be extracted and added to the users link_list (see below).
text
enabled_for_email Enable the user to receive email. If set to false this user will never receive any email from Pathable whatsoever.
boolean
visible Show the user within the community. If set to false the user will not be visible in any lists or searches. Until they sign in and confirm their profile.
boolean
allowed_mails Message classes this user can be sent. Includes “reset_password”, “custom”, “private_notices”, “public_notices”, “daily_update”, and “system.” This will be expanded when the user first signs in to the system. We recommend that users initially be set to “reset_password”, “custom”, “private_notes”, and “public_notes”.
string (comma separated values)
photo_deferred_url A valid URL pointing to a user profile photo. The URL will be automatically retrieved, cropped, and converted to three graduated sizes.
URL
link_list A comma or space separated list of links. Twitter links of the form http://twitter.com/<username> and https://twitter.com/search?q=<query< are automatically recognized, processed and tracked.
URL
answers_attributes[question_id] The numerical ID of the question that the answer is to map to. This can be be found through the host tools by inspecting the URL when editing a question (e.g., http://example.pathable.com/host#questions/14 means the question_id is 14
integer
answers_attributes[answer] A string answer to the paried question ID. Comma separated values will automatically be parsed into Groups, Tags, or Categories appropriatley.
string

Responses:

The index of users when paginating through all results or when searching includes:

{
  total_entries: 881
  total_pages: 45
  per_page: 20
  current_page: 1
  results: [
    {
      id: 3413
      class_name: "User"
      created_at: 1319832914000
      updated_at: 1322150169000
      to_param: "jordan-schwartz"
      cached_slug: "jordan-schwartz"
      first_name: "Jordan"
      last_name: "Schwartz"
      full_name: "Jordan Schwartz"
      friendly_name: "Jordan Schwartz"
      credentials: "PhD"
      title: "President"
      organization_name: "Pathable, Inc."
      bio: ""
      enabled_for_email: true
      visible: true
      has_accepted_legal: true
      dirty: true
      allowed_mails: ["reset_password","custom", "private_notices", "public_notices"]
      photo_url_cropped: "http://urlcom/image.jpg"
      photo_url_full: "http://urlcom/image.jpg"
      user_contactees: []
      categories: []
      ribbons: []
      labels: []
    }
  ]
}

A single users data after getting, creating or updating:

{
  id: 3413
  created_at: 1319832914000
  updated_at: 1322150169000
  to_param: "jordan-schwartz"
  first_name: "Jordan"
  last_name: "Schwartz"
  ...
}

Examples:

You can get lists of users with GET requests and pagination options.

curl -H "Api-Token: 3d98d63c-ef88-4dc6-a5d5-068ffc8bf6ae" -X GET http://api.pathable.com/v1/communities/45333/users.json?per_page=50&page=2 -v

Search for a user by email:

curl -H "Api-Token: 3d98d63c-ef88-4dc6-a5d5-068ffc8bf6ae" --data "conditions[email]=email@example.com" -X GET http://api.pathable.com/v1/communities/45333/users.json? -v

You can get a user including full meeting and group details using GET with a specific user ID.

curl -H "Api-Token: 3d98d63c-ef88-4dc6-a5d5-068ffc8bf6ae" -X GET http://api.pathable.com/v1/communities/45333/users/4510.json -v

You can create a new user with a POST request. You must include an auth_token for a user with admin privileges. Typically this is the account you use to sign-in to and manage your event.

curl -H "Api-Token: 6c22149c-1c96-4e46-b645-123123123456" -d "primary_email=bugs@bunny.com" -d "first_name=Bugs" -d "last_name=Fudd" -d "answers_attributes[][question_id]=766&answers_attributes[][answer]=Hound" -d "auth_token=qj123asd23WUfrs47yjm" -X POST http://api.pathable.com/v1/communities/45333/users.json -v

You can update an existing user with a PUT request to a URL that includes the users ID.

curl -H "Api-Token: 3d98d63c-ef88-4dc6-a5d5-068ffc8bf6ae" -d"first_name=Changed" -d "auth_token=ekejidjad9ad09Dilas" -X POST http://api.pathable.com/v1/communities/45333/users/3413.json -v

Sending Mail

You can send users email using community templates.

End points

/mails.json

Request Methods:

GET

Parameters:

user_ids A list of user IDs to whom mail should be sent.
template_name The template name to use.

Examples:


curl -H "Api-Token: b525570f-511c-4923-86bc-839ee225e98f" --data "user_ids[]=456&template=custom%2Fjoin_community" -X POST http://api.pathable.com/v1/communities/123/mails.json?auth_token=3d98d63c-ef88-4dc6-a5d5-068ffc8bf6ae

Response:

The response will have a 200 status code if the message was send correctly or a 404 if the template couldn’t be found.

Organizations

You can retrieve information on organizations, including exhibitors and sponsors of an event.

End points

/organizations.json
/organizations/<id>.json

Response:

{
  total_entries: 881
  total_pages: 45
  per_page: 20
  current_page: 1
  results: [
    { 
      "id": 6201,
      "class_name": "Organization",
      "created_at": 1320077847000,
      "updated_at": 1320189154000,
      "to_param": "6201",
      "name": "AOL Advertising",
      "blurb": "Stop by our booth to rest your feet, recharge, and meet the Team. ",
      "friendly_name": "Company",
      "private": false,
      "logo_url_full": "http://url.com/1320189153.jpg",
      "logo_url_cropped": "http://url.com/1320189153.jpg",
      "memberships_count": 0,
      "color": null,
      "booth": "First floor",
      "level": null,
      "sponsor": true,
      "labels": []
    }
  ]
}

Meetings

You can retrieve meeting information for all or specific communities (and events). You can also get meeting information scoped to a specific user including busy times and private meetings scheduled with other attendees. Requests are always scoped via the URL.

End points

/meetings.json
/meetings/<id>.json
/users/<id>/meetings.json
/users/<id>/meetings/<id>.json

Request Methods:

GET

Parameters:

conditions[name] Filter meetings by name.

Response:

{
  total_entries: 1000
  total_pages: 50
  per_page: 20
  current_page: 1
  results: [
    {
      id: 6428
      class_name: "Groups::Meetings::Meeting"
      created_at: 1320189272000
      updated_at: 1320434398000
      to_param: 6428
      name: "James Conard, Cloud Experience Closing"
      blurb: "Closing by James Conard, Microsoft"
      friendly_name: "James Conard, Cloud Experience Closing"
      private: false
      logo_url_full: "http://url.com/full.gif"
      logo_url_cropped: "http://url.com/cropped.gif"
      memberships_count: 19
      color: null
      time_zone_offset: -25200
      starts_at: 1320277500000
      ends_at: 1320278400000
      location_name: "Room 202"
      community_id: 5778
      location_id: 147
      url: "http://sic2011.pathable.com/#meetings/6428"
      labels: [
        {
          id: 19
          class_name: "Groups::Meetings::Label"
          created_at: 1320077875000
          updated_at: 1320077875000
          name: "Cloud Computing"
          color: null
          label_set_id: 43
          label_set: {
            id: 43
            name: "Track"
          }
        }
      ]
      speakerships: []
      location: {
        id: 147
        class_name: "Location"
        created_at: 1320077883000
        updated_at: 1320077883000
        name: "Room 202"
        managed: false
        reservable: false
        community_id: 5778
      }
    }
  ]
}

Examples:

Get a list of all meetings across all events:

curl -H "Api-Token: 3d98d63c-ef88-4dc6-a5d5-068ffc8bf6ae" -X GET http://api.pathable.com/v1/meetings.json&auth_token=23lk4j234923l -v

Get a list of all meetings for a specific community:

curl -H "Api-Token: 3d98d63c-ef88-4dc6-a5d5-068ffc8bf6ae" -X GET http://api.pathable.com/v1/communities/123/meetings.json&auth_token=23lk4j234923l -v

Get a list of events a specific user is attending at a specific community:

curl -H "Api-Token: 3d98d63c-ef88-4dc6-a5d5-068ffc8bf6ae" -X GET http://api.pathable.com/v1/communities/123/users/456/meetings.json&auth_token=23lk4j234923l -v

Attendee Schedules

You can manage attendee relationships with meetings using the memberships API. POST to create a new membership between a user and a meeting or group. DELETE to remove an existing membership by ID.

End points

/meetings/<id>/memberships/<id>.json

Request Methods:

GET
POST
DELETE

Parameters:

user_id The user ID to which the scoped meeting should be associated.
integer
status The attendance status of the user to the meeting. One of pending, accepted, declined or unresponded.
string

Response:

{
    "answer_id": null, 
    "class_name": "Groups::Meetings::Attendance", 
    "created_at": 1340051098000, 
    "group": {
        "accepted_memberships_count": 0, 
        "blurb": "About this meeting", 
        "class_name": "Groups::Meetings::Meeting", 
        "closed": true, 
        "color": null, 
        "created_at": 1316552426000, 
        "friendly_name": "Testing Repeats", 
        "id": 345, 
        "label_names": [], 
        "memberships_count": 3, 
        "name": "Testing Repeats", 
        "private": true, 
        "updated_at": 1319224581000
    }, 
    "id": 781522, 
    "requester_id": 38024, 
    "ribbon_id": null, 
    "roles": [], 
    "status": "pending", 
    "status_message": null, 
    "updated_at": 1340051098000, 
    "user_id": 38024
}

Examples:

Create a membership between a user and a meeting.

curl -H "Api-Token: b9da1513-0bb7-234-8c4f-548cb94a2346" -H "Accepts: application/json" -d "auth_token=mN9ip3XHKtpE5y" -d "user_id=38024" -X POST http://api.pathable.com/v1/communities/292/meetings/345/memberships.json -v

Pathable APIs

Contents

Contents