CityGro REST API Documentation
CityGro provides an application programming interface (API) to make it possible to integrate the power of CityGro into custom applications (your own “app”). This API makes it possible to create CityGro Contacts based on events that happen in your app as well as trigger CityGro Actions and CityGro Automations.
Already got the API thing down?
If you have heard of the “Postman” app, you might be better served by playing around with CityGro’s Postman API Collection. Keep in mind that there are 2 environment variables you need to have for all requests to succeed: Auth-Token and contact_id. By default the Auth-Token is for CityGro’s sandbox account and contact_id is a contact that may not currently exist. Click below to get started:
What exactly is an API?
The power of a computer application is increased when an application can connect with other computer applications. For example, Intuit’s Mint application, with your permission, can connect and watch your bank account and can assist in creating reliable budgets.
FedEx and UPS provide means which sites like eBay and PayPal can connect on to print shipping labels. Mobile app developers can write apps to interface with cameras, accelerometers, touch devices, and microphones through defined protocols provided by software such as Android and iOS. An API is a defined protocol that software developers can use to leverage the power of another system without having to know exactly how that system works.
Who can benefit by using an API?
Perhaps you manage a web site that collects data from your visitors and want to market to your visitors based on their demographics, or maybe you are looking to compare your existing customer data with the data in your CityGro account to maintain consistency. Anyone with any custom solution can benefit from using CityGro’s API. Using CityGro’s API you can instantly create or interact with the contacts in your CityGro Portal by sending notifications to CityGro’s API server from your app.
How do I start?
If you know how to write code, the below instructions will look familiar to you. If you don’t know how to code, you’ll need to hire a developer who does. Though this API follows the latest best practices and is built on popular and tried/tested standards, it still requires some programming “know-how” to get what you need done. Keep in mind that the application that you build will have full access to your list of contacts on CityGro, so care must be exercised when writing your code.
Basic API Documentation
The purpose of this documentation is to illustrate how to read and update data from a contact within CityGro. There are a few prerequisite terms that are specific to CityGro that are used throughout this documentation and should be understood before continuing.
- Contact – A representation of your customer or site visitor; any entity that you wish to track and communicate with.
- Data Field – The basic unit of storage in a CityGro Contact. Data Fields can store one or more values of text, numbers, images, dates/times, or JSON objects. Once a data field is created it can be deleted but cannot be modified. Data Fields have keys that are used as identifiers and must be unique and without special characters.
- Group - The means of logically segmenting Contacts within CityGro. Contacts can belong to as many groups as desired. Groups can be nested infinitely deep. When selecting the contacts in a parent group, all contacts belonging to child groups of that group are also selected.
- API Token – A long jumbled string of random looking text that is your “password” for using the API. This token should be kept as safe as your password. This token can be found or generated within the Settings section of the CityGro Portal. Full access privileges are required to view and manage API tokens.
- Schema – The list of Data Fields associated with a CityGro account that can be used. There is currently no limit to how many Data Fields can be created. All available Data Fields and their respective keys can be found on the Data Fields page within the Contacts section of the CItyGro Portal.
Step 1: Creating a new CityGro Contact
CityGro’s API follows the the REST protocol. A full explanation of RESTful standards and practices can be found in this article on Wikipedia. This makes it possible to use the entire API while only needing to understand a single concept. Please note that all successful API requests will return with a 200 HTTP status code when successful.
To create a contact you’ll simply make a HTTP POST request to…
…with request data like this…
…and with the content type set to “application/json” and a JSON object of containing all of the data fields to be stored with the contact. Every contact (and entity within CityGro) has an “_id” field that contains the unique identifier of the entity. When creating a new contact CityGro’s server assigns a value to this _id automatically. The entire new Contact is returned from this call. Take note of the _id field as you’ll need it for the rest of these API calls.
Step 2: Reading your new CityGro Contact
To retrieve the Contact you just created, pass the _id that was returned to you in Step 1 in the URL of a GET request like this…
Step 3: Updating your new CityGro Contact
To update the first name of your new contact to be “Johnny” instead of “Jonny”, simply pass only the first_name field to the API. By default the CityGro API performs a PATCH-like update making it possible to update only certain parts of a contact rather than having to pass the entire contact.
Step 4: Deleting your new CityGro Contact
To delete you simply need to call a delete request to the same URL as above.
By this point you should now understand how to create, read, update, and delete a contact on CityGro. This same pattern can be extended to all other API endpoints such as Fields, Groups, and Messages.