Working with Objects

📘

Don't have an Instabot account yet?

Start your free trial today!

Contents

  1. Basic Operations
  2. Creating Objects
  3. Updating Objects
  4. Retrieving Objects
  5. Deleting Objects
  6. Searching Objects
    6a. Get Total Count
    6b. Paging
    6c. Sorting
    6d. Search Criteria
  7. Resolving Objects
  8. System Properties
  9. Custom Properties

1. Basic Operations

Each object type is accessible at a specific endpoint, and provides specific operations via different HTTP methods in a REST-like approach. For example, the table below listed common operations for the User object. Depending on the object type there can be more or less methods, but in general almost every entity has methods listed below.

v1/users

POST

Create new user

v1/users/{id}

GET

Get user details by id

v1/users/{id}

PUT

Update user details

v1/users/{id}

DELETE

Delete user

v1/users/{id}

POST

Delete user

v1/users

GET

Search for users

v1/users/query

POST

Search for users


2. Creating Objects

Below is an example of creating an user via API:

curl -X POST \
        "https://api.instabot.io/v1/users" \
    -H "X-Instabot-Api-Key: {API_KEY}" \
    -H "Authorization:X-Instabot-Master-Api-Key {API_MASTER_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"username":"newuser", "userpassword":"123", "email":"[email protected]"}'

If the user creation is OK, then the API will respond with HTTP Status 201 and a body (data) containing the id of created user object.

{
    "apiStatusCode" : "Success",
    "data": {
        "objectId" : 400
    }
}

3. Updating Objects

To update object, send a PUT request to the object endpoint

curl "-X PUT" \
        "https://api.instabot.io/v1/users/400" \
    -H "X-Instabot-Api-Key: {API_KEY}" \
    -H "Authorization:X-Instabot-Master-Api-Key {API_MASTER_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"username":"newuser", "email":"[email protected]"}'

4. Retrieving Objects

To get information about an existing object, send a GET request to the object endpoint specifying the ObjectId as the last part of URL.

curl -X GET \
        "https://api.instabot.io/v1/users/400" \
    -H "X-Instabot-Api-Key: {API_KEY}" \
    -H "Authorization:X-Instabot-Master-Api-Key {API_MASTER_KEY}"

5. Deleting Objects

Objects can be deleted by sending a DELETE request to the object endpoint

curl -X DELETE \
        "https://api.instabot.io/v1/users/400" \
    -H "X-Instabot-Api-Key: {API_KEY}" \
    -H "Authorization:X-Instabot-Master-Api-Key {API_MASTER_KEY}"

If object was deleted by mistake and need to be restored it is possible to do by sending POST request to object endpoint

curl -X POST \
        "https://api.instabot.io/v1/users/400" \
    -H "X-Instabot-Api-Key: {API_KEY}" \
    -H "Authorization:X-Instabot-Master-Api-Key {API_MASTER_KEY}"

6. Searching for Objects

🚧

When searching for user objects, make sure type=all is included in your request so that the API returns both anonymous and known users in the user search response.

There are 2 methods of searching for objects:

  1. GET
  2. POST

Both methods works in the same way. The only difference is the how the search criteria is passed to the API. For a GET request, it is passed via a query string:

curl -X GET \
        "https://api.instabot.io/v1/users?type=all" \
    -H "X-Instabot-Api-Key: {API_KEY}" \
    -H "Authorization:X-Instabot-Master-Api-Key {API_MASTER_KEY}" \
    -G \
    --data-urlencode 'query={"email":"[email protected]"}'

And for a POST request, search criteria is sent in the body to accommodate for more search data:

curl -X POST \
        "https://api.instabot.io/v1/users/query?type=all" \
    -H "X-Instabot-Api-Key: {API_KEY}" \
    -H "Authorization:X-Instabot-Master-Api-Key {API_MASTER_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"name":"John"}'

Once the search is completed, the API will return a response with the following structure:

{
    "apiStatusCode" : "Success",
    "hasMoreRecords" : "true",
    "data": [
        { },
        { },
        ...
        { }
    ]
}

The data field will be contain an array of objects and an additional field hasMoreRecords in the top level of the returned JSON. If true, the hasMoreRecords field indicates that there are more items to fetch.


6a. Searching for Objects - Get Total Count

By default, the API does not return the total number of items in the response because of the server-side overhead required to calculate this number on every request.

However, if you want to get the count, you can pass the getTotalCount=true query parameter in your query search:

curl https://api.instabot.io/v1/users/query?getTotalCount=true \
    -X POST \
    -H "X-Instabot-Api-Key: {API_KEY}" \
    -H "Authorization:X-Instabot-Master-Api-Key {API_MASTER_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"name":"John"}'

Upon success API should respond with JSON containing totalCount field at the root:

{
    "apiStatusCode" : "Success",
    "hasMoreRecords" : "true",
    "totalCount" : 156,
    "data": [
        { },
        { },
        ...
        { }
    ]
}

It is recommended to not overuse this option, and for you to request the total count only in situations where it is required. In general, API calls made without needing to calculate the total number of items should respond faster.


6b. Searching for Objects - Paging

Paging can be controlled via query string parameters:

limit

10

number of items to return in response

skip

0

number of items to skip from the beginning of list

For example, you get the first 20 items of the first page, you can send the following request:

curl https://api.instabot.io/v1/users?limit=20&skip=0 \
    -X GET \
    -H "X-Instabot-Api-Key: {API_KEY}" \
    -H "Authorization:X-Instabot-Master-Api-Key {API_MASTER_KEY}"

And to get the next 20 items in the second page:

curl https://api.instabot.io/v1/users?limit=20&skip=20 \
    -X GET \
    -H "X-Instabot-Api-Key: {API_KEY}" \
    -H "Authorization:X-Instabot-Master-Api-Key {API_MASTER_KEY}"

6c. Searching for Objects - Sorting

Objects returned by search methods can be sorted if required. This is controlled by the orderBy query string parameter. It is a comma-separated list of property names, each property name can be followed by asc/desc word to specify sort direction. Here are some examples of valid queries:

  •         `/v1/users?orderBy=name`
    
  •         `/v1/users?orderBy=name desc`
    
  •         `/v1/users?orderBy=name desc,email asc`
    
  •         `/v1/users?orderBy=name,email`
    
  •         `/v1/users?orderBy=name,email desc`
    

6d. Searching for Objects - Search Criteria

Search criteria is complex JSON object where you can specify search operands and combine them by logical operations.

Here is the formal definition of the search criteria structure:

<Query> = {<LogicalExpression>}
<LogicalExpression> = "AND":[{<LogicalExpression>},...] ||
                      "OR":[{<LogicalExpression>},...] || 
                      "NOT":{ <LogicalExpression>} ||
                      <FieldName>:<Comparison>
<Comparison> =  <Value> || 
                {<operator>:<Value>}

For example, imagine that you need to filter a collection by complex criteria like so:

NOT( (field1>value1) AND (field2<value2) ) OR ( (field3=value3) AND (field4=value4 OR field5=value5) )

In JSON, this expression will be represented as follows:

{"OR": [
        { "NOT": {
               "AND": [
                {"field1" : {"$gt" : value1}},
                {"field2" : {"$lt" : value2}}
           ]
     }},
     {"AND": [
           {"field3": value3},
           {"OR": [
                {"field4": value4},
                {"field5": value5}
           ]}
     ]}
]}

The Instabot API supports the following operators in search criteria:

Equals

{"firstName":"John"}

Not Equals

{"firstName":{"$ne":"John"}}

Greater Than

{"firstName":{"$gt":"John"}}

Greater Than or Equal To

{"firstName":{"$gte":"John"}}

Less Than

{"firstName":{"$lt":"John"}}

Less Than or Equal To

{"firstName":{"$lte":"John"}}

Empty

{"firstName":null}

Not Empty

{"firstName":{"$ne":null}}

In List

{"firstName":{"$in":["John",”Adam”]}}

Not In List

{"firstName":{"$nin":["John",”Adam”]}}

Starts With

{"Name":{"$startsWith":"John"}}

Ends With

{"Name":{"$endsWith":"Smith"}}

Contains

{"Name":{"$contains":"Smith"}}

Be advised that null values are not allowed inside $in/$nin operators and will cause an exception. If you need to do so, please use construction as follows:
$in : "OR": [ {"field1":{"$in":[value1,value2,value3]}}, {"field1":null}]
$nin : "AND": [ {"field1":{"$nin":[value1,value2,value3]}}, {"field1":{"$ne":null} }]


7. Resolving Objects

When the API returns a response and the data has a complex structure with references to nested objects, by default the API will not return nested objects. The API will only return references to the nested objects.

However, it is possible for the request API to return these objects in a single response by using the resolve query string parameter and specifying the name of the fields that require resolution by separating each of them with a comma.

For example, the below method returns information about the Referral Discount; by default the API will return references to users related to a particular discount:

{
    ...
    "ambassadorUser" : {
        "objectId" : 100
    },
    "referralUser" : {
        "objectId" : 200
    }
}

To get the response with additional fields for these objects, send the following request:

curl -X GET \
        "https://api.instabot.io/v1/promo/referrals/discounts/100?resolve=ambassadorUser,referralUser" \
    -H "X-Instabot-Api-Key: {API_KEY}"

And the API will respond with these objects in response:

{
    ...
 
    "ambassadorUser" : {
        "objectId" : 100,
        "email" : "[email protected]",
        ...
    },
    "referralUser" : {
        "objectId" : 200,
        "email" : "[email protected]",
        ...
    }
}

Resolving is supported for methods returning single items, and also for methods returning collections of items.
In some cases objects will have references to several objects. For example, a single user can be included within several Organizations. By default, if a user object is requested from the API, the returned will not include the organizations property.

But, if the User is requested with resolution, a list of user organizations will be returned within the response:

curl -X GET \
        "https://api.instabot.io/v1/users/100?resolve=organizations" \
    -H "X-Instabot-Api-Key: {API_KEY}" \
    -H "Authorization:X-Instabot-Master-Api-Key {API_MASTER_KEY}"

8. System Properties

Every object in the Instabot API has properties created by the system. These systemProperties are returned within the object but can't be modified. Some objects have more system properties, some have less, but the 3 fields below will be present in every object:

objectId

integer

Unique object Identifier

createDate

date

Generated by the system when object created

updateDate

date

Generated by the system when object updated


9. Custom Properties

Some Instabot objects can be extended with custom properties. Such objects will have the nested JSON field customProperties in its structure. But before using them it is required setup custom properties schema. This can be done either through the Instabot portal, or the Instabot API. Currently the following Objects can be extended with custom properties:

  • User
  • User Segment
  • Organization
  • Content Item
  • Content Group

In API methods for editing custom properties schema for specific object are accessible via /customproperties endpoint located under object endpoint. For example, to update User custom properties schema you should work with /v1/users/customproperties endpoint.

v1/users/customproperties

POST

Create custom property

v1/users/customproperties/{id}

GET

Get custom property

v1/users/customproperties/{id}

PUT

Update custom property

v1/users/customproperties/{id}

DELETE

Delete custom properties

v1/users/customproperties

GET

Get list of custom properties

Custom Property Object Schema

Type

Constraints

Comments

name

string

Required, Unique

Unique name of custom property

description

string

Description of custom property

fieldType

enumeration

Required

Type of the custom property. Available values:

  • "string"
  • "integer"
  • "boolean"
  • "decimal"
  • "double"
  • "dateTime"
  • "guid"
  • "objectRef"

objectEntityType

enumeration

Required if "fieldType" is set to "objectRef"

Type of the object used as a custom property. Available values:

  • "user"
  • "userSegment"
  • "organization"
  • "contentItem"
  • "contentGroup"
  • "file"
  • "fileGroup"

isUnique

bool

If "true" then API will be checking field values for uniqueness. Default value = false

isList

bool

if "true" then instead of single value custom field will contain array of values. Default value = false