Socialize API Documentation¶

Welcome! Here you’ll find the public documentation of the Socialize API. You can use this API in order to integrate Socialize functionality into your apps. This API is currently used in the apps built through AppMakr with Socialize enabled.

Base URL¶

All URLs referenced in the documentation have the following base:

http://api.getsocialize.com/

Common Features¶

Detailed descriptions of OAuth headers can be found here.

Required Headers¶

The following headers are required unless otherwise specified in the service description.

oauth_consumer_key: The identifier portion of the client credentials (equivalent to a username).
oauth_nonce: A nonce is a random string, uniquely generated by the client.
oauth_signature: A signature generated using the signature method to allow the server to verify the request.
oauth_signature_method: Required to be HMAC-SHA1
oauth_timestamp: Unix timestamp in seconds from epoch: 01/01/1970 00:00:00 GMT
oauth_token: The token value used to associate the request with the resource owner. This is optional for Authentication.

Optional Headers¶

oauth_version: If provided this header is required to be 1.0

Request Details¶

All requests use http except for the Authentication request, which uses https.
Authentication method uses the following rules:
- Authentication is done using OAuth
- The Authorization header is used as the OAuth transmission method.
- The OAuth signature method is provided using the oauth_signature_method header

Post request uses the following Content-Type header:

Content-Type: application/x-www-form-urlencoded

Request parameter requirements:
- All PUT/POST methods require a payload parameter that is a json dictionary containing the appropriate parameters for that method.
- See specific API documentation for the contents of the payload dictionary.
- All methods that create objects optionally accept lat and lng keys for each object which provide geographic co-ordinates.
All response bodies are in json format.

Note

Dates and times conform to the Unicode Standard.
The general format used is <YYYY-MM-DD HH:MM:SS+HHHH>.
An example date is 2011-07-10 00:12:13+0000.
The last four numbers indicate the timezone offset.
The strftime standard format string used to produce this format is %Y-%m-%d %H:%M:%S%z

Pagination¶

These fields are optional.

Natural pagination uses first and last fields to specify a range for pagination. First is included, and last is excluded.

Dynamic pagination is achieved using limiting_id and limit. Response will return n items (when n = limit) whose id is less than limiting_id; the limiting_id is not included in the response. Resultset is ordered by id, descending.

Default values:

first = 0
last = 100

limiting_id = null
limit = 100

Note

Each request is limited to 100 items.
If first = 0, last = 50, the API returns shares 0-49.
If last - first > 100, then last is truncated to equal first + 100. For example, if first = 100, last = 250, then last is changed to last = 200.
If only last = 150 is passed, then last is truncated to 100. If last = 25, then results 0...24 are returned.

API¶

Authentication¶

Service Details
Path	/v1/authenticate/
HTTPS	✓
Method(s)	POST
OAuth Required	✗

Request Parameters
Name	Type	Required	Multiple OK	Description
udid	String	✓	✗	This is a unique identifier for the device or application requesting authentication.
auth_token	String	✗	✗	The 3rd party auth token for the 3rd party user.
auth_token_secret	String	✗	✗	The 3rd party auth token’s secret for the 3rd party user.
auth_type	Integer	✗	✗	The type of 3rd party.

Response Components
Name	Type	Description
oauth_token	String	The OAuth token associated with the user.
oauth_token_secret	String	The OAuth secret associated with the user.
user	Object	The User Object associated with the request.

Note

A API User Object will always be created if this is request is made without OAuth headers and third-party credentials.
Third party authentication accepts credentials for the following two providers. The index is what needs to be passed in for the auth_type parameter.
- [1] Facebook
- [2] Twitter
Third Party Authentication uses a service such as Facebook to verify the user.
- Using third party authentication allows the user to maintain a profile that is linked to their activity.
- Without using Third Party Authentication, the user will still be able to access socialize features but these actions will not be linked to the user’s profile.
- If third-party credentials and OAuth headers are provided, the User Object in the response may point to a different user if the third-party credentials already exist and are associated with another device or user. At this time there is no way to resolve this conflict.
- If third-party credentials and OAuth headers are provided, and a different set of credentials already exist, the credentials will be updated.

Examples

Request Default authentication request

http://api.getsocialize.com/v1/authenticate/

payload = { "udid": 1234345656 }

Request Authentication request with third party tokens (twitter)

http://api.getsocialize.com/v1/authenticate/

payload = {
    "udid": 1234345656
    "auth_token": "1238676487328972345abcdef98374",
    "auth_secret": "some-really-secretive-secret",
    "auth_type": 2
}

Response

{
    “oauth_token”: <str>,
    “oauth_token_secret”: <str>,
    “user”: <User Object>
}

Application¶

Service Details

Path /v1/application/current/

HTTPS No

HTTP Methods GET

OAuth Required Yes

There are no Request Parameters

Response Components

Name Type Description

items List Application Full Object

errors Object Error Object details if any.

Entity¶

Service Details
Path	/v1/entity/<entity-key>/
HTTPS	✗
Method(s)	GET POST
OAuth Required	✓

Any one entity can be fetched by GET-ing a URL of the form:

http://api.getsocialize.com/v1/entity/<base64-encoded-key>/

Making such a request will return one object of the requested entity. Details about the objects are specified in Request/Response Objects.

Note

The key must be base-64 encoded. This is to work around various limitations of having encoded URLs inside another URL.

Examples

Request

http://api.getsocialize.com/v1/entity/aHR0cDovL2F3ZXNvbWUuaGFycGIuY29tLw==/

Response jobs

<Full Entity Object>

Request Parameters (GET)
Name	Type	Required	Multiple OK	Description
id	Integer	✗	✓	The id(s) of the type of activity.
entity_key	String	✗	✓	The key of the entity.
sort	String	✗	✗	The sort order desired. At this time only “total_activity” is allowed.

Request Parameters (POST)
Name	Type	Required	Multiple OK	Description
key	String	✓	✗	The key of the entity. See Notes for additional details.
meta	String	✗	✗	An additional data about the object.
name	String	✓	✗	A name identifying the entity.
type	String	✗	✗	The type of entity. Only choice : `url`.

Response Components
Name	Type	Description
items	List	A Full Entity Object
errors	Object	Error Object details if any.
total_count	Integer	Count of items associated with this entity. This is only returned for GET requests.

Note

If you specify a key that already exists, the entity will be updated with the name.

Examples

Request GET latest 100 entities in the application

http://api.getsocialize.com/v1/entity/

Request Get entities by specific entity IDs

http://api.getsocialize.com/v1/entity/?id=13&id=42&id=117

Request GET an entity by a key

http://api.getsocialize.com/v1/entity/?entity_key=http%3A%2F%2Fexample.com

Request GET entities by keys sorted by total activity

http://api.getsocialize.com/v1/entity/?entity_key=http%3A%2F%2Fexample.com&entity_key=http%3A%2F%2Fgoogle.com&sort=total_activity

Response

{
    “items”: [ <Full Entity Object> ],
    “errors”: [ <Error Object> ]
}

Entity Activities¶

Activities can be of four types:

Comments

Likes

Shares

Views

Fetching Activities¶

To get all activities associated with any given entity you can use the activity endpoint.

Service Details
Path	/v1/activity/
HTTPS	✗
Method(s)	GET
OAuth Required	✓

Request Parameters (GET)
Name	Type	Required	Multiple OK	Description
entity_key	String	✗	✗	The key of the entity.
first	Integer	✗	✗	See Pagination for details.
last	Integer	✗	✗	See Pagination for details.

Response Components
Name	Type	Description
items	List	Comment Object, Share Object, Like Object with type
errors	Object	Error Object details if any.
total_count	Integer	Count of items associated with this entity. This is only returned for GET requests.

Note

If entity_key is not provided then all activities associated with the application are returned. This could be a very expensive operation and should not be used unless absolutely needed.

Any one activity can be fetched by GET-ing a URL of the form:

http://api.getsocialize.com/v1/<activity-type>/<activity-id>/

Making such a request will return one object of the requested activity type. Details about the objects are specified in Request/Response Objects.

Examples

Request

http://api.getsocialize.com/v1/comment/123/

Response

<Comment Object>

Request

http://api.getsocialize.com/v1/like/123/

Response

<Like Object>

Request :: Get likes based on an entity key

http://api.getsocialize.com/v1/like/?entity_key=<some-entity-key>

Response

{
    “items”: [ <Like Object> ],
    “errors”: [ <Error Object> ],
}

Request :: Get comments based on an entity key

http://api.getsocialize.com/v1/comment/?entity_key=<some-entity-key>

Response

{
    “items”: [ <Comment Object> ],
    “errors”: [ <Error Object> ],
}

Deleting Activities¶

Any one activity can be deleted by DELETE-ing a URL of the form:

http://api.getsocialize.com/v1/<activity-type>/<activity-id>/

Examples

Request

telnet api.getsocialize.com 80
DELETE /v1/comment/123
Host: api.getsocialize.com
Content-Length: 0
Authorization: ....

Note

If the item was previously deleted or does not exist a 404 Not Found is returned.

Comment¶

Service Details
Path	/v1/comment/<comment-id>
HTTPS	✗
Method(s)	GET POST DELETE
OAuth Required	✓

Request Parameters (GET)
Name	Type	Required	Multiple OK	Description
id	Integer	✗	✓	The id(s) of the type of activity.
entity_key	String	✗	✗	The key of the entity.
first	Integer	✗	✗	See Pagination for details.
last	Integer	✗	✗	See Pagination for details.
limiting_id	Integer	✗	✗	See Pagination for details.
limit	Integer	✗	✗	See Pagination for details.

Request Parameters (POST)
Name	Type	Required	Multiple OK	Description
entity_key	String	✓	✗	The key of the entity. See Notes for additional details.
entity	Object	✓	✗	If an entity does not already exist for the comment it creates one. See Notes for additional details.
lat	Float	✗	✗	Latitude information for geo data.
lng	Float	✗	✗	Longitude information for geo data.
propagation	Propagator Object	✗	✗	A mean to push a message to the user’s third party stream using Propagator Object
propagation_info_request	PropagationInfoRequest Object	✗	✗	A mean to get a list of short urls when pushing a message to third party via the SDK. The list of urls in added to PropagationInfoRequest Object object inside each activity object.
share_location	Boolean	✗	✗	Whether to share location with others. Defaults to True
subscribe	Boolean	✗	✗	Whether to subscribe to notifications for this entity. Defaults to null
text	String	✓	✗	Text content of the comment.

Response Components
Name	Type	Description
items	List	A Comment Object
errors	Object	Error Object details if any.
total_count	Integer	Count of items associated with this entity. This is only returned for GET requests.

Note

For GET requests only one of id or entity_key can be provided.
For POST requests only one of entity_key or entity can be provided. See examples for concrete usage.
If entity is provided, and one does not already exist, an entity will be created for you.

Examples

Request GET last 100 comments for an application.

http://api.getsocialize.com/v1/comment/

Request GET comments by specific comment IDs

http://api.getsocialize.com/v1/comment/?id=13&id=42&id=117

Request GET 25 comments for an entity using range.

http://api.getsocialize.com/v1/comment/?entity_key=http%3A%2F%2Fexample.com&first=0&last=25

Request POST a comment for an existing entity

http://api.getsocialize.com/v1/comment/

payload = [
    {
        "entity_key": "http://getsocialize.com",
        "text": "POST comment #1",
        "lat": "37.786521",
        "lng": "-122.397850"
    }
]

Request POST a comment and create or update and entity

http://api.getsocialize.com/v1/comment/

payload  = [
    {
        "entity": {
                "key": "http://getsocialize.com",
                "name": "New Entity"
               },
        "lat": "37.786521",
        "lng": "-122.397850",
        "share_location": false,
        "text": "POST comment #2",
        "subscribe": false
    }
]

Response

{
    “items”: [ <Comment Object> ],
    “errors”: [ <Error Object> ],
    “total_count”: <int - only for GET>
}

Like¶

Service Details
Path	/v1/like/<like-id>
HTTPS	✗
Method(s)	GET POST DELETE
OAuth Required	✓

Request Parameters (GET)
Name	Type	Required	Multiple OK	Description
id	Integer	✗	✓	The id(s) of the type of activity.
entity_key	String	✗	✗	The key of the entity.
first	Integer	✗	✗	See Pagination for details.
last	Integer	✗	✗	See Pagination for details.
limiting_id	Integer	✗	✗	See Pagination for details.
limit	Integer	✗	✗	See Pagination for details.

Request Parameters (POST)
Name	Type	Required	Multiple OK	Description
entity_key	String	✓	✗	The key of the entity. See Notes for additional details.
entity	Object	✓	✗	If an entity does not already exist for the like it creates one. See Notes for additional details.
lat	Float	✗	✗	Latitude information for geo data.
lng	Float	✗	✗	Longitude information for geo data.
propagation	Propagator Object	✗	✗	A mean to push a message to the user’s third party stream using Propagator Object
propagation_info_request	PropagationInfoRequest Object	✗	✗	A mean to get a list of short urls when pushing a message to third party via the SDK. The list of urls in added to PropagationInfoRequest Object object inside each activity object.
share_location	Boolean	✗	✗	Whether to share location with others. Defaults to True

Response Components
Name	Type	Description
items	List	A Like Object
errors	Object	Error Object details if any.
total_count	Integer	Count of items associated with this entity. This is only returned for GET requests.

Note

For GET requests only one of id or entity_key can be provided.
For POST requests only one of entity_key or entity can be provided. See examples for concrete usage.
If entity is provided, and one does not already exist, an entity will be created for you.

Examples

Request GET last 100 likes for an application.

http://api.getsocialize.com/v1/like/

Request GET likes by specific like IDs

http://api.getsocialize.com/v1/like/?id=13&id=42&id=117

Request GET 25 likes for an entity using range.

http://api.getsocialize.com/v1/like/?entity_key=http%3A%2F%2Fexample.com&first=0&last=25

Request POST a like for an existing entity

http://api.getsocialize.com/v1/like/

payload = [
    {
        "entity_key": "http://getsocialize.com",
        "lat": "37.786521",
        "lng": "-122.397850"
    }
]

Request POST a like and create or update and entity

http://api.getsocialize.com/v1/like/

payload  = [
    {
        "entity": {
                "key": "http://getsocialize.com",
                "name": "New Entity"
               },
        "lat": "37.786521",
        "lng": "-122.397850",
        "share_location": false,
    }
]

Response

{
    “items”: [ <Like Object> ],
    “errors”: [ <Error Object> ],
    “total_count”: <int - only for GET>
}

Share¶

Service Details
Path	/v1/share/<share-id>
HTTPS	✗
Method(s)	GET POST DELETE
OAuth Required	✓

Request Parameters (GET)
Name	Type	Required	Multiple OK	Description
id	Integer	✗	✓	The id(s) of the type of activity.
entity_key	String	✗	✗	The key of the entity.
first	Integer	✗	✗	See Pagination for details.
last	Integer	✗	✗	See Pagination for details.
limiting_id	Integer	✗	✗	See Pagination for details.
limit	Integer	✗	✗	See Pagination for details.

Request Parameters (POST)
Name	Type	Required	Multiple OK	Description
entity_key	String	✓	✗	The key of the entity. See Notes for additional details.
entity	Object	✓	✗	If an entity does not already exist for the share it creates one. See Notes for additional details.
lat	Float	✗	✗	Latitude information for geo data.
lng	Float	✗	✗	Longitude information for geo data.
medium	Integer	✓	✓	An integer representing on which medium the share was made. See Medium Notes
propagation	Propagator Object	✗	✗	A mean to push a message to the user’s third party stream using Propagator Object
propagation_info_request	PropagationInfoRequest Object	✗	✗	A mean to get a list of short urls when pushing a message to third party via the SDK. The list of urls in added to PropagationInfoRequest Object object inside each activity object.
share_location	Boolean	✗	✗	Whether to share location with others. Defaults to True
text	String	✓	✗	Text content of the share.

Note

The medium parameter can have one of the following values:

[1] Twitter
[2] Facebook
[3] Email
[4] SMS
[101] Other

Response Components
Name	Type	Description
items	List	A Share Object
errors	Object	Error Object details if any.
total_count	Integer	Count of items associated with this entity. This is only returned for GET requests.

Note

For GET requests only one of id or entity_key can be provided.
For POST requests only one of entity_key or entity can be provided. See examples for concrete usage.
If entity is provided, and one does not already exist, an entity will be created for you.

Examples

Request GET last 100 shares for an application.

http://api.getsocialize.com/v1/share/

Request GET shares by specific share IDs

http://api.getsocialize.com/v1/share/?id=13&id=42&id=117

Request GET 25 shares for an entity using range.

http://api.getsocialize.com/v1/share/?entity_key=http%3A%2F%2Fexample.com&first=0&last=25

Request POST a share for an existing entity

http://api.getsocialize.com/v1/share/

payload = [
    {
        "entity_key": "http://getsocialize.com",
        "text": "POST share #1",
        "medium": 2,
        "lat": "37.786521",
        "lng": "-122.397850"
    }
]

Request POST a share and create or update and entity

http://api.getsocialize.com/v1/share/

payload  = [
    {
        "entity": {
                "key": "http://getsocialize.com",
                "name": "New Entity"
               },
        "lat": "37.786521",
        "lng": "-122.397850",
        "share_location": false,
        "medium": 2,
        "text": "POST share #2",
    }
]

Response

{
    “items”: [ <Share Object> ],
    “errors”: [ <Error Object> ],
    “total_count”: <int - only for GET>
}

View¶

Service Details
Path	/v1/view/<view-id>
HTTPS	✗
Method(s)	GET POST
OAuth Required	✓

Request Parameters (GET)
Name	Type	Required	Multiple OK	Description
id	Integer	✗	✓	The id(s) of the type of activity.
entity_key	String	✗	✗	The key of the entity.
first	Integer	✗	✗	See Pagination for details.
last	Integer	✗	✗	See Pagination for details.
limiting_id	Integer	✗	✗	See Pagination for details.
limit	Integer	✗	✗	See Pagination for details.

Request Parameters (POST)
Name	Type	Required	Multiple OK	Description
entity_key	String	✓	✗	The key of the entity. See Notes for additional details.
entity	Object	✓	✗	If an entity does not already exist for the view it creates one. See Notes for additional details.
lat	Float	✗	✗	Latitude information for geo data.
lng	Float	✗	✗	Longitude information for geo data.
propagation	Propagator Object	✗	✗	A mean to push a message to the user’s third party stream using Propagator Object
propagation_info_request	PropagationInfoRequest Object	✗	✗	A mean to get a list of short urls when pushing a message to third party via the SDK. The list of urls in added to PropagationInfoRequest Object object inside each activity object.
share_location	Boolean	✗	✗	Whether to share location with others. Defaults to True

Response Components
Name	Type	Description
items	List	A View Object
errors	Object	Error Object details if any.
total_count	Integer	Count of items associated with this entity. This is only returned for GET requests.

Note

For GET requests only one of id or entity_key can be provided.
For POST requests only one of entity_key or entity can be provided. See examples for concrete usage.
If entity is provided, and one does not already exist, an entity will be created for you.

Examples

Request GET last 100 views for an application.

http://api.getsocialize.com/v1/view/

Request GET views by specific view IDs

http://api.getsocialize.com/v1/view/?id=13&id=42&id=117

Request GET 25 views for an entity using range.

http://api.getsocialize.com/v1/view/?entity_key=http%3A%2F%2Fexample.com&first=0&last=25

Request POST a view for an existing entity

http://api.getsocialize.com/v1/view/

payload = [
    {
        "entity_key": "http://getsocialize.com",
        "lat": "37.786521",
        "lng": "-122.397850"
    }
]

Request POST a view and create or update and entity

http://api.getsocialize.com/v1/view/

payload  = [
    {
        "entity": {
                "key": "http://getsocialize.com",
                "name": "New Entity"
               },
        "lat": "37.786521",
        "lng": "-122.397850",
        "share_location": false,
    }
]

Response

{
    “items”: [ <View Object> ],
    “errors”: [ <Error Object> ],
    “total_count”: <int - only for GET>
}

User¶

Fetching Users¶

Service Details
Path	/v1/user/<user-id>
HTTPS	✗
Method(s)	GET POST
OAuth Required	✓

Request Parameters (GET)
Name	Type	Required	Multiple OK	Description
id	Integer	✗	✓	The id of the user(s).

Request Parameters (POST)
Name	Type	Required	Multiple OK	Description
id	Integer	✗	✗	The id of the user(s).
date_of_birth	Date	✗	✗	DOB in YYYY/MM/DD format.
description	String	✗	✗	Any description text.
email	String	✗	✗	Email address.
first_name	String	✗	✗	First name.
last_name	String	✗	✗	Last name.
location	String	✗	✗	Location of user.
meta	String	✗	✗	Upto 1024 bytes of app defined meta-data in plain-text format. Could be used to store JSON or XML data.
picture	String	✗	✗	Base64 encoded version of the users image to store.
sex	String	✗	✗	Sex of user. One of M or F.
quiet_start_time	Time	✗	✗	Start time from which to silence notifications. Time in HH:MM format in 24 hr notation.
quiet_end_time	Time	✗	✗	Time from which to enable notifications. Time in HH:MM format in 24 hr notation.
timezone	String	✗	✗	Timezone string based on tzinfo data. See Timezone Data for valid strings.

Response Components
Name	Type	Description
items	List	A Full User Object
errors	Object	Error Object details if any.
total_count	Integer	Count of items associated with this entity. This is only returned for GET requests.

Note

If no id is provided, the user associated with the access token will be retrieved.
A user can only update their own profile using the POST request. Attempts to do so by other users will return a HTTP 401 error.

Examples

Request GET last 100 users for an application.

http://api.getsocialize.com/v1/user/

Request GET users by specific user IDs

http://api.getsocialize.com/v1/user/?id=13&id=42&id=117

Activities¶

Service Details
Path	/v1/user/<user-id>/<activity\|like\|comment\|share\|view>/
HTTPS	✗
Method(s)	GET
OAuth Required	✓

Request Parameters (GET)
Name	Type	Required	Multiple OK	Description
id	Integer	✗	✗	The id of the user.

Request Parameters (DELETE /v1/user/<user-id>/like/)
Name	Type	Required	Multiple OK	Description
entity_key	String	✓	✗	The entity_key used to filter the set of activities.

Response Components
Name	Type	Description
items	List	A Comment Object or a Like Object or a Share Object or a View Object or the first three
errors	Object	Error Object details if any.
total_count	Integer	Count of items associated with this entity. This is only returned for GET requests.

Note

In case multiple activities are requested using the activity endpoint each object will also have an activity_type field which can be one of comment, share, like

Examples

Request: get the latest 100 activities by the user’s id:

GET /v1/user/123/activity/

Request: get the latest 10 activities by the user’s id:

GET /v1/user/123/activity/?last=10

Request: get the latest 100 likes by the user’s id:

GET /v1/user/123/like/

Request: get the latest 10 likes by the user’s id:

GET /v1/user/123/like/?last=10

Request: delete a like by the user’s id and entity_key:

DELETE /v1/user/123/like/?entity_key=http://getsocialize.com

Request: get the latest 100 comments by the user’s id:

GET /v1/user/123/comment/

Request: get the latest 100 shares by the user’s id:

GET /v1/user/123/share/

Request: get the latest 100 views by the user’s id:

GET /v1/user/123/view/

Response

{
    "items": [ <Comment>, <Like>, <Share> ],
    "errors": [ <Error> ],
    "total_count": <int>
}

Devices¶

Service Details
Path	/v1/user/device/
HTTPS	✗
Method(s)	POST
OAuth Required	✓

Request Parameters (POST)
Name	Type	Required	Multiple OK	Description
c2dm_registration_id	String	✗	✗	The registration_id given by Google C2DM. REQUIRED when `device_type` : “Android”.
device_token	String	✗	✗	The device token to register with the system. REQUIRED when `device_type` : “iOS”.
device_type	String	✓	✗	The type of device. One of ‘iOS’ or ‘Android’

Response Components
Name	Type	Description
items	List	A DeviceToken Object
errors	Object	Error Object details if any.

Note

When device_type is Android then c2dm_registration_id is required
When device_type is iOS then device_token is required

Examples

Request Associate an Apple device token with a user

[
    {
        "device_token": "26fb2d4ffb8594883d89f827162036e4fea7e02fe1f18256b27717f03cdefa98",
        "device_type: "iOS",
    }
]

Request Associate an android device token with a user and set quite time between 9pm to 7am GMT:

[
    {
        "c2dm_registration_id": "APA91bFt0CDXzlUueWZACY-nKHWDp...KTVZyb99B313QLIzch5eZiR64rRkzpciTg",
        "device_type: "Android",
    }
]

Response

{
    “items”: [ <DeviceToken Object> ],
    “errors”: [ <Error Object> ],
}

Subscriptions¶

Service Details
Path	/v1/user/subscription/
HTTPS	✗
Method(s)	GET POST
OAuth Required	✓

Request Parameters (GET)
Name	Type	Required	Multiple OK	Description
entity_key	String	✗	✗	The key of the entity.
first	Integer	✗	✗	See Pagination for details.
last	Integer	✗	✗	See Pagination for details.
limiting_id	Integer	✗	✗	See Pagination for details.
limit	Integer	✗	✗	See Pagination for details.

Request Parameters (POST)
Name	Type	Required	Multiple OK	Description
entity_key	String	✓	✗	The key of the entity. See Notes for additional details.
type	String	✓	✗	The type pf subscriptons. See Subscription Type Notes
subscribe	Boolean	✗	✗	Whether to subscribe to notifications for this entity. Defaults to null

Note

The type parameter can have one of the following values:

[1] new_comment

Response Components
Name	Type	Description
items	List	A Subscription Object
errors	Object	Error Object details if any.

Examples

Request latest 100 subscriptions of the user:

/user/subscription/

Request by a key and a range

/user/subscription/?entity_key=http%3A%2F%2Fexample.com

Request subscribe a user for notifications about an entity:

[
    {
        "entity_key": "http://getsocialize.com",
        "type": "new_comments"
    }
]

Request unsubscribe a user from notifications to an entity:

[
    {
        "entity_key": "http://getsocialize.com",
        "type": "new_comments",
        "subscribed": false
    }
]

Response

{
    “items”: [ <Subscription Object> ],
    “errors”: [ <Error Object> ],
}

Device Token¶

Service Details
Path	/v1/device/check/
HTTPS	✗
Method(s)	POST
OAuth Required	✓

Request Parameters (POST)
Name	Type	Required	Multiple OK	Description
device_token	String	✓	✓	The device token to check.

Examples

Request Check for multiple device tokens

[
    {"device_token": "002861827E7EB5CE7035B7C9F23F473D"},
    {"device_token": "002861827E7EB5CE7035B7C9F23F473E"}
]

Response

{
    “002861827E7EB5CE7035B7C9F23F473D”: <DeviceToken Object or null>,
    “002861827E7EB5CE7035B7C9F23F473E”: <DeviceToken Object or null>,
}

Utility¶

URL Shortener¶

Service Details
Path	/v1/user/shorten/
HTTPS	✗
Method(s)	POST
OAuth Required	✓

Request Parameters (POST)
Name	Type	Required	Multiple OK	Description
entity_key	String	✓	✗	The key of the entity. See Notes for additional details.

Response Components
Name	Type	Description
items	List	A string with the shortened URL.
errors	Object	Error Object details if any.

Examples

Request shorten a url:

{
    "entity_key": "http://getsocialize.com"
}

Third-Party Accounts¶

Service Details
Path	/v1/third_party/
HTTPS	✗
Method(s)	DELETE
OAuth Required	✓

Request Parameters (DELETE)
Name	Type	Required	Multiple OK	Description
auth_type	Integer	✗	✗	The type of 3rd party.

Response Components
Name	Type	Description
oauth_token	String	The OAuth token associated with the user.
oauth_token_secret	String	The OAuth secret associated with the user.
user	Object	The User Object associated with the request.

Note

This endpoint is used to dis-associate a third-party account with the Socialize user. This is to be used when a user tries to associate a third-party account and the API server returns a different user object than the user who sent the request.
This request needs to be signed with the credentials of the old user associated with the third-party account.
Third party authentication accepts credentials for the following two providers. The index is what needs to be passed in for the auth_type parameter.
- [1] Facebook
- [2] Twitter

Examples: Request To delete a third-party association

/v1/third_party/?auth_type=1

Request/Response Objects¶

All types of parameters or return values are indicated as <TYPE>.

<Application> Application Object

<ApplicationFull> Application Full Object

<Attachment> Attachment Object

<Comment> Comment Object

<Connection> Connection Object

<CreateEntity> Create Entity Object

<Entity> Entity Object

<FullEntity> Full Entity Object

<Error> Error Object

<Invitation> Invitation Object

<Like> Like Object

<Propagator> Propagator Object

<PropagationInfoRequest> PropagationInfoRequest Object

<PropagationInfoResponse> PropagationInfoResponse Object

<Share> Share Object

<ShareMedium> ShareMedium Object

<Subscription> Subscription Object

<User> User Object

<UserFull> Full User Object

<View> View Object

Default Application Object:

{
    id: <Integer>,
    name: <String>,
}

Default Application Full Object contains:

{
    android_package_name: <String>,
    apple_store_id: <String>,
    category: <String>,
    description: <String>,
    id: <int>,
    name: <String>,
    notifications_enabled: <boolean>,
}

Default Attachment Object:

{
    entity_id: <int>,
    mimetype: <String>,
    url: <String>
}

Default Comment Object:

{
  application: <Application>,
  date: <String>,
  entity: <Entity>,
  id: <int>,
  lat: <float>,
  lng: <float>,
  propagation_info_response: <PropagationInfoResponse>,
  share_location: <boolean>,
  text: <String>,
  user: <User>,
}

Default Connection Object:

{
  type: <String>,
  user: <User>,
}

DeviceToken Object:

{
  application: <Application>,
  c2dm_registration_id: <String>,
  device_token: <String>,
  device_type: <String>,
  user: <User>,
}

Create Entity Object contains (use this object when a new entity is being created):
{
    key: <String>
    name: <String>
}

Default Entity Object:

{
  comments: <int>,
  id: <int>,
  key: <String>,
  likes: <int>,
  name: <String>,
  shares: <int>,
  type: <String>
  views: <int>,
}

type = [‘url’, ‘text’]

Full Entity Object:

{
  attach_token: <String>,
  attachments: [<Attachment>],
  comments: <int>,
  id: <int>,
  key: <String>,
  likes: <int>,
  meta: <String>,
  name: <String>,
  shares: <int>,
  type: <String>
  views: <int>,
}

type = [‘url’, ‘text’]

Default Error Object:
{
  error: <String>,
  payload: <object>
}
<object> : could be a String or dictionary.

Default Like Object:

{
  application: <Application>,
  date: <String>,
  entity: <Entity>,
  id: <int>,
  lat: <float>,
  lng: <float>,
  propagation_info_response: <PropagationInfoResponse>,
  share_location: <boolean>,
  user: <User>,
}

Default Like Object:

{
  hash_key: <String>,
  identifier: <String>,
  third_party: <String>,
  url: <String>,
  user: <User>,
}

Default Propagator Object:
{
  extra_params: <String>,
  third_parties: [List],
}
third_parties choice(s) : twitter

Default PropagationInfoRequest Object:
{
  extra_params: <String>,
  third_parties: [List],
}
third_parties choice(s) : email, facebook, sms, twitter

Default PropagationInfoResponse Object: this object is included in response object for each activity: Comment Object, Like Object, Share Object and View Object.
{
    <third_party> : {
       "application_url": <String>,
       "entity_url": <String>,
    }
}
<third_party> would be the item passed in Propagator Object and/or PropagationInfoRequest Object in third_parties field.

Default Share Medium Object:
{
  id: <int>,
  medium: <String>,
}

Default Subscription Object:

{
  date: <String>,
  entity: <Entity>,
  id: <int>,
  subscribed: <boolean>,
  type: <String>,
  user: <User>,
}

Default User Object:

{
  city: <String>,
  first_name: <String>,
  id: <int>,
  last_name: <String>,
  meta: <String>,
  small_image_uri: <String>,
  state: <String>,
  third_party_auth: [
        {
            auth_type: <String>,
            auth_id: <int>,
        }
    ]
  username: <String>,
}

Full User Object:

{
  description: <String>,
  first_name: <String>,
  id: <int>,
  large_image_uri: <String>,
  last_name: <String>,
  location: <String>,
  medium_image_uri: <String>,
  meta: <String>,
  quiet_end_time: <time-string>,
  quiet_start_time: <time-string>,
  sex: <String>,
  small_image_uri: <String>,
  stats: {
             views: <int>,
             likes: <int>,
             comments: <int>,
             share: <int>,
           },
  third_party_auth: [
        {
            auth_type: <String>,
            auth_id: <int>,
        }
    ],
  timezone: <String>
  username: <String>,
}

Default View Object:

{
  application: <Application>,
  date: <String>,
  entity: <Entity>,
  id: <int>,
  lat: <float>,
  lng: <float>,
  propagation_info_response: <PropagationInfoResponse>,
  share_location: <boolean>,
  user: <User>,
}

Service Details
Path	/v1/application/current/
HTTPS	No
HTTP Methods	GET
OAuth Required	Yes

`<Application>`	Application Object
`<ApplicationFull>`	Application Full Object
`<Attachment>`	Attachment Object
`<Comment>`	Comment Object
`<Connection>`	Connection Object
`<CreateEntity>`	Create Entity Object
`<Entity>`	Entity Object
`<FullEntity>`	Full Entity Object
`<Error>`	Error Object
`<Invitation>`	Invitation Object
`<Like>`	Like Object
`<Propagator>`	Propagator Object
`<PropagationInfoRequest>`	PropagationInfoRequest Object
`<PropagationInfoResponse>`	PropagationInfoResponse Object
`<Share>`	Share Object
`<ShareMedium>`	ShareMedium Object
`<Subscription>`	Subscription Object
`<User>`	User Object
`<UserFull>`	Full User Object
`<View>`	View Object

Navigation

Socialize API Documentation¶

Base URL¶

Common Features¶

Required Headers¶

Optional Headers¶

Request Details¶

Pagination¶

API¶

Authentication¶

Application¶

Entity¶

Entity Activities¶

Fetching Activities¶

Deleting Activities¶

Comment¶

Like¶

Share¶

View¶

User¶

Fetching Users¶

Activities¶

Devices¶

Subscriptions¶

Device Token¶

Utility¶

URL Shortener¶

Third-Party Accounts¶

Request/Response Objects¶

Table Of Contents

Quick search

Navigation