Working with Objects

📘
Don't have an Instabot account yet?
Start your free trial today!

Basic Operations
Creating Objects
Updating Objects
Retrieving Objects
Deleting Objects
Searching Objects
6a. Get Total Count
6b. Paging
6c. Sorting
6d. Search Criteria
Resolving Objects
System Properties
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:

GET
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

Working with Objects

📘
Don't have an Instabot account yet?

Contents

1. Basic Operations

2. Creating Objects

3. Updating Objects

4. Retrieving Objects

5. Deleting Objects

6. Searching for Objects

🚧

6a. Searching for Objects - Get Total Count

6b. Searching for Objects - Paging

6c. Searching for Objects - Sorting

6d. Searching for Objects - Search Criteria

7. Resolving Objects

8. System Properties

9. Custom Properties

Custom Property Object Schema

📘Don't have an Instabot account yet?

Contents

1. Basic Operations

2. Creating Objects

3. Updating Objects

4. Retrieving Objects

5. Deleting Objects

6. Searching for Objects

🚧

6a. Searching for Objects - Get Total Count

6b. Searching for Objects - Paging

6c. Searching for Objects - Sorting

6d. Searching for Objects - Search Criteria

7. Resolving Objects

8. System Properties

9. Custom Properties

Custom Property Object Schema

📘
Don't have an Instabot account yet?