Introduction

Welcome! Here you’ll find the public documentation for Socialize APIs.

Developers can use Developer API for integrating Socialize functionality into mobile apps.

The Management API allows developer to progamatically perform actions on their socialize applications.

Base URL

All URLs referenced in the documentation have the following base:

http://api.getsocialize.com/

Oauth 1.0

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

Developer API

Developer API is used for integrating Socialize functionality into mobile apps.

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

  • An API User Object will always be created if the request is made without OAuth Token and/or 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.

  • Important Use Cases:
    1. If OAuth token is provided but user is not associated to any third party, then we treat the request as regular non-oauth token request.
    2. If the user is currently anonymous on Device A and has never authenticated previously then chooses to authenticate with Twitter or FaceBook they are given a NEW user with TW/FB attached.
    3. If the user is currently anonymous on Device A but has previously authenticated in the SAME APP on Device B with Twitter, then elects to authenticate on Device A with Twitter they are “switched” to the same user that they were using on Device B.
    4. If the user is currently anonymous on Device A but has previously authenticated in the SAME APP on Device B with Twitter, then elects to authenticate on Device A with FaceBook they are given a NEW user with FaceBook attached.
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.

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>,
}

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. Defaults to 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) DEPRICATED AUG 23 2012
header-rows:1
       
stub-columns:1
       
widths:20
10 10 10 60
         
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) DEPRICATED AUG 23 2012
header-rows:1
       
stub-columns:1
       
widths:20
10 10 10 60
         
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) DEPRICATED AUG 23 2012
header-rows:1
       
stub-columns:1
       
widths:20
10 10 10 60
         
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) 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.
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.

Note

  • 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 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> ],
}

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>/
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/

Response

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

Devices

Service Details
Path /v1/user/device/
HTTPS
Methodod(s) POST
OAuth Required

Request Parameters (POST)
Name Type Required Multiple OK Description
c2dm_registration_id String The registration_id given by Google C2DM.
gcm_registration_id String The gcm_registration_id given by Google Clound Messaging.
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’
service_type String Available options: ANDROID_C2DM, ANDROID_GCM, APNS_DEVELOPMENT, and APNS_PRODUCTION. service_type is required if specifying gcm_registration_id, but not for c2dm_registration_id.

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 or gcm_registration_id is required
  • When device_type is iOS then device_token is required
  • If service_type is provided, then for iOS device it is set to APNS_PRODUCTION and ANDROID_C2DM for an Android device.
Examples

Request Associate an Apple device token with a user

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

Request Associate a C2DM registration id. We generate the device_token on our backend:

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

Request Associate a GCM registration id. We generate the device_token on our backend:

[
    {
        "device_type: "Android",
        "gcm_registration_id": "APA91bFt0CDXzlUueWZACY-nKHWDp...KTVZyb99B313QLIzch5eZiR64rRkzpciTg",
        "service_type: "ANDROID_GCM",
    }
]

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. entity_notification
  2. 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> ],
}

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

Common Features

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>,
  gcm_registration_id: <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>,
  user_action_summary: {
    comments: <int>,
    likes: <int>,
    shares: <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 Object:

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

Default Share Medium Object:

{
  id: <int>,
  medium: <String>,
}
Media:
Shares occur across a specific medium. Here are the list of media that can currently be set to indicate where the item was shared
  1. Twitter
  2. Facebook
  3. Email

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>,
}

Management API

Here you’ll find the public documentation of the Socialize Management API. This API can be used to programmatically perform actions on your socialize applications.

Smart Alert

Service Details
Path /management/v1/smart_alert/
HTTPS
Method(s) GET POST
OAuth Required

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

/management/v1/smart_alert/<id>/

Request Method: POST

Send a notification to an application’s users.

Payload:
"application_id": <int>,
"broadcast_user_set" : <string>,
"devices": [list],
"entity_id": <int>,
"message": <string>,
"subscription": <string>,
"url": <string>,
"users": [list]

application_id (required): identifies application.

broadcast_user_set (optional): Only available when sending a broadcast using developer_direct_entity.

Defaults to application_users. Available options:

  1. application_users
  2. entity_users

devices (optional): A list of devices to whom the message is sent. For android devices, this could be the C2DM registration id and/or the server-side generated device token.

entity_id (optional): entity_id to include as part of notification data. Required for subscriptions=”developer_direct_entity”.

message (required): message to send. Restricted to 180 characters.

subscription (optionsl): The type of notification to be sent.

Defaults to developer_notification. Available options:

  1. developer_notification
  2. developer_direct_entity
  3. developer_direct_url
  4. entity_notification

url (optional): A url to include as part of notification data. Required for subscriptions=”developer_direct_url”.

users (optional): A list of users to whom the message is sent. If not provided, then the message is sent to all of the application’s users, unless a list of devices is provided.

Response:

200:Returns the smart alert id.

Example:

{
  "android": {
    "under_quota": true,
    "will_cause_quota_overflow": false
  },
  "ios": {
    "under_quota": true,
    "will_cause_quota_overflow": false
  },
  "smart_alert_id": 222
}
400:Oauth errors and payload issues..

Example:

{
    "application_id":["This application does not belongs to you."]
}