Swoogo API Docs

Check out our new and improved documentation on ReadMe.io! Welcome to the Swoogo API! You can use our API to access Swoogo API endpoints, which can get information on events, registrations, sessions and more.Swoogo uses API keys to allow access to the API. You can generate or re-generate your API key for a particular account and user by logging in to the app and visiting Profile > API Credentials. Rate Limits In order to ensure that the API remains accessible to all users, we have a rate limit of 2000 credits in every 10 minute period. The number of “credits” that your call will cost depends on the call type. If “getting all records”, the call will cost 10 credits, if viewing a single record it will cost 1 credit. Authenticating Using Curl and PHP: ``` php $consumerKey = urlencode('CONSUMER_KEY'); $consumerSecret = urlencode('CONSUMER_SECRET'); $ch = curl_init(); curl_setopt($ch, CURLOPT_USERPWD, $consumerKey.':'.$consumerSecret); curl_setopt($ch, CURLOPT_URL, 'https://api.swoogo.com/api/v1/oauth2/token.json'); curl_setopt($ch, CURLOPT_POSTFIELDS, 'grant_type=client_credentials'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $result = json_decode(curl_exec($ch)); $accessToken = $result->access_token; ``` To use the Swoogo API class, simply include the class and use: ``` php $api = new SwoogoApi('CONSUMER_KEY', 'CONSUMER_SECRET'); ``` Make sure to replace CONSUMER_KEY AND CONSUMER_SECRET with your actual API credentials. Step 1: Find your consumer key and secret Your consumer key and secret can be found by logging in to Swoogo, and going to My Profile > API Credentials. Step 2: Encode consumer key and secret The steps to encode your consumer key and secret into a set of credentials to obtain a bearer token are: 1) URL encode the consumer key and the consumer secret according to RFC 1738.2) Concatenate the encoded consumer key, a colon character “:”, and the encoded consumer secret into a single string.3) Base64 encode the string from the previous step. Consumer Key:xvz1evFS4wEEPTGEFPHBogConsumer Secret:L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOgConcatenated:xvz1evFS4wEEPTGEFPHBog:L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOgBase 64 Encoded:eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJnNmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw== Step 3: Obtain a bearer token The value calculated in step 1 must be exchanged for a bearer token by issuing a request to POST /api/v1/oauth2/token.json: The request must be a HTTP POST request.The request must include an Authorization header with the value of your base 64 encoded token (from step 1).The request must include a Content-Type header with the value of application/x-www-form-urlencoded;charset=UTF-8.The body of the request must be grant_type=client_credentials. Example request: POST /api/v1/oauth2/token.json HTTP/1.1Host: api.swoogo.comAuthorization: Basic YOUR_BASE_64_ENCODED_TOKENContent-Type: application/x-www-form-urlencoded;charset=UTF-8Content-Length: 29grant_type=client_credentials Step 4: Authenticate API requests with the bearer token The bearer token may be used to issue requests to Swoogo API endpoints. To use the bearer token, construct a normal HTTPS request and include an Authorization header with the value of your bearer token from step 2. Example request: GET /api/v1/events.json HTTP/1.1Host: api.swoogo.comAuthorization: Bearer YOUR_BEARER_TOKEN Bearer tokens expire every 30 minutes - do not rely on them remaining the same. The token API call will return a field called "expires_at", which is a UTC timestamp letting you know when the current token will expire. Searching When querying the API for all of an object type - for example querying for all events - you can optionally provide a “search” parameter to narrow down the result set. This takes the form of the attribute you are searching on, the search operator and the value to search for. Available search operators: To specify multiple search operators, simply comma separate them. For example to search for events where name is equal to “Test Event” and id is not equal to 100, you would pass the following string as the search parameter: “name=Test Event,id!=100” Errors The Swoogo API uses the following error codes: Error CodeMeaning400Bad Request – Your request is wrong401Unauthorized – Your API credentials are wrong403Forbidden – You don’t have permissions to view the resource you requested404Not Found – The specified resource could not be found405Method Not Allowed – You tried to access a resource with an invalid method415Unsupported media type. The requested content type or version number is invalid.418I’m a teapot422Data validation failed (in response to a POST request, for example). Please check the response body for detailed error messages.429Too Many Requests – You’re requesting too many resources! Slow down!500Internal Server Error – We had a problem with our server. Try again later.503Service Unavailable – We’re temporarially offline for maintanance. Please try again later. General Formatting Conventions - **IDs** - When sending an ID such as an event_id or registrant_id all IDs should be integer values - **Date-times** - Should be an ISO 8601 timestamp - Example - YYYY-MM-DD HH:MM:SS - If only the date is needed use YYYY-MM-DD - If only the time is needed use HH:MM:SS - **Time-zones** - Can be sent as abbreviation, for example UTC or EST - List - [https://en.wikipedia.org/wiki/List_of_time_zone_abbreviations](https://en.wikipedia.org/wiki/List_of_time_zone_abbreviations) - **Currencies** - Use 3 letter format - ISO 4217 - List - [https://en.wikipedia.org/wiki/ISO_4217](https://en.wikipedia.org/wiki/ISO_4217) - **Addresses** - All country fields should use ISO 3166 Alpha-2 codes - State and province names should use the common 2 character acronym - **Boolean** - When sending true or false values use a 1 or 0 as an integer - When you receive a json response true and false will be a primitive boolean type - **Expand** - Some GET requests can include the “expand” parameter - Expand value should be the singular comma separated object type - Example - contact,location,registrant **Phone Number Format** We suggest all phone numbers to be submitted in the E.164 format. This means you should include the country code (e.g., +1 for the USA), followed by the national number without spaces or special characters. Here are some examples: - United States: `+1234567890` - United Kingdom: `+447911123456` - Australia: `+61412345678` - Germany: `+4915112345678` Following this format helps us ensure your number is valid and usable worldwide. For more details, you can learn about the E.164 standard [here](https://en.wikipedia.org/wiki/E.164). If this format is not received we attempt to assign the correct country code but it is not guaranteed to be correct.