Back to top

Upfluence software

Introduction

The Upfluence software API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors.

Authentication

The authentication to access to the Upfluence software API is made using an access_token redeemed by the https://identity.upfluence.co/token endpoint following the OAuth2 protocol. You can find some documentation about this endpoint here.

Authentication to the API can be performed in two different ways:

Bearer auth

You can add the Authorization HTTP header to your request with Bearer <access_token> as value.

Such as:

$ curl -H "Authorization: Bearer <access_token>" "https://api.upfluence.co/v1/influences/42"

URL parameter

You can also add the query parameter access_token in your URI and add your access token as value.

Warning: If you provide the access_token in the URI, you have to URL encode it.

Such as:

$ curl "https://api.upfluence.co/v1/influences/42?access_token=<access_token>"

Errors

Upfluence software uses conventional HTTP response codes to indicate the success or failure of an API request.

In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with Upfluence’s servers (these are rare).

HTTP status code summary

Status code Meaning
200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to a missing required parameter.
401 - Unauthorized No valid access_token provided.
402 - Too Many Requests You exceeded your allocated number of API calls.
404 - Not Found The requested resource doesn’t exist.
500, 502, 503, 504 - Server Errors Something went wrong on Upfluence’s end. (These are rare.)

Rate Limit

To avoid abuse, some endpoints have limitations.

These limits are applied on the following endpoints:

  • POST /v1/matches

  • GET /v1/influencers/{id}

The number of credit spent is the number of influencer fetched (displayed / exported)

Each month the number of credit spent is reset.

How to get the limit and how much has been spent

Each time you make a call to one of these endpoints, we add to the response some additional HTTP Headers:

  • X-Endpoint-Limit: indicates your number of credit per month

  • X-Endpoint-Spent: indicates the number of credit you spent over the last 30 days

Here is an example:

HTTP/1.1 200 OK
...
X-Endpoint-Limit: 10000
X-Endpoint-Spent: 12
...

Limitation exceeded

If you exceed your limitations, a response with the HTTP status 402 will be returned.

Here is an example:

HTTP/1.1 402
...
{
  "error": "Limit exceeded"
}

Terminology

Criteria

A criteria is a predicate which allows you to do a full text search over a specific field or the full influencer profile.

Payload format

A criteria is composed of four key/values:

key description
Field The field of the influencer profile to look into
Type The type of predicate to use in this part of the query
Weight How much this clause matter compared to the others. It influences the relevancy
Value The term(s) to find into the selected field(s)

Here is an example of a criteria payload:

{
  "field": "all",
  "type": "should",
  "weight": 1.0,
  "value": "technology"
}

Criteria fields

key description
all Looking for the term(s) in all fields
influencer.name Name
influencer.email Email
youtube.name Youtube name
youtube.username Youtube channel ID
youtube.description Youtube description
youtube.videos.name Youtube videos name
youtube.videos.description Youtube videos description
instagram.username Instagram username
instagram.website Instagram website
instagram.bio Instagram bio
instagram.media.text Instagram post caption
instagram.media.location_name Instagram post location name
blog.title Blog title
blog.description Blog description
blog.url Blog url
blog.articles.title Article title
blog.articles.description Article description
blog.articles.content Article content
blog.articles.url Article URL
twitter.name Twitter name
twitter.screen_name Twitter screen name
twitter.bio Twitter bio
twitter.url Twitter url
twitter.tweets.content Tweet content
facebook.name Facebook name
facebook.bio Facebook bio
facebook.url Facebook url
facebook.statuses.text Facebook status text
pinterest.username Pinterest username
pinterest.first_name Pinterest first name
pinterest.last_name Pinterest last name
pinterest.bio Pinterest bio
pinterest.pins.title Pin title
pinterest.pins.description Pin description

Criteria type

type description
should One of the criteria predicate should be satisfied
must This criteria predicate has to be satisfied to match this influencer
must_not This criteria predicate has to be wrong to match this influencer

Filter

String filter

This filter allows you to search results which content a specifc string value in a field.

It’s commonly used to search influencers based in a specific country.

key description
field The field / data , to apply the filter on
value The string value to search
negative true or false, define an exclusion (true) or an inclusion (false)

Here is an example:

{
  "type": "string",
  "field": "influencer.country",
  "value": "US",
  "negative": false
}

Multi string filter

This filter allows you search results containing one of the values in a field.

It’s commonly used to search influencers based in a specific country.

key description
field The field / data , to apply the filter on
value Array of string

Here is an example:

{
  "type": "multi-string",
  "field": "influencer.geo_country",
  "value": ["CA", "US"],
}

Valid fields for String and Multi string filters:

field description
influencer.lang Influencer’s language
influencer.geo_country Influencer’s country

Int filter

Filter results based on an operation in an int value

It’s commonly used to search influencers with more or less than XX followers.

key description
field The field / data , to apply the filter on
value The value to use
order One of: < less than, > greater than, = equal
negative true or false, define an exclusion (true) or an inclusion (false)

Here is an example:

{
  "type": "int",
  "field": "twitter.followers",
  "value": 1500,
  "order": ">",
  "negative": false
}

You can use this filter to find influencers with a post matching a specific time criteria.

You can use the following fields:

  • youtube.videos.timestamp: To find influencers with a youtube video posted at/before/after a specific date

  • blog.articles.timestamp: To find influencers with an article posted at/before/after a specific date

  • facebook.status.timestamp: To find influencers with a facebook post posted at/before/after a specific date

  • twitter.tweets.timestamp: To find influencers with a tweet posted at/before/after a specific date

  • instagram.medias.timestamp: To find influencers with an instagram post posted at/before/after a specific date

  • pinterest.pins.timestamp: To find influencers with a pin posted at/before/after a specific date

The value associated with this filter must be UNIX timestamp based on the UTC timezone.

Here is an example:

To match all influencers with an instagram post created in 2019, you can write:

{
  "type": "int",
  "field": "instagram.medias.timestamp",
  "value": 1546300800, // Unix Timestamp of 2019-01-01 00:00:00 UTC
  "order": ">",
  "negative": false
}

Multi int filter

This filter corresponds to the IN (:array) sql filter.

It’s commonly used to search influencers based on their id.

key description
field The field / data , to apply the filter on
value Array of int
negative true or false, define an exclusion (true) or an inclusion (false)

Here is an example:

{
  "type": "multi-int",
  "field": "influencer.id",
  "value": [1, 2, 3],
  "negative": true
}

Valid field for Int and Multi int filters:

field description
influencer.id Influencer id
youtube.engagement_rate Influencer’s Youtube engagement rate
youtube.views Influencer’s total Youtube views
youtube.followers Influencer’s Youtube followers
youtube.average_views Influencer’s Youtube videos average views
youtube.average_engagements Influencer’s Youtube videos average engagements
youtube.average_likes Influencer’s Youtube videos average likes
youtube.average_comments Influencer’s Youtube videos average comments
youtube.videos.timestamp Match a specific creation timestamp of a youtube video
instagram.engagement_rate Influencer’s Instagram engagement rate
instagram.followers Influencer’s Instagram followers
instagram.average_engagements Influencer’s Instagram media average engagements
instagram.average_comments Influencer’s Instagram media average comments
instagram.average_likes Influencer’s Instagram media average likes
instagram.medias.timestamp Match a specific creation timestamp of an instagram post
blog.engagement_rate Influencer’s blog engagement rate
blog.alexa_rank Influencer’s blog alexa rank
blog.average_engagements Influencer’s blog average engagements
blog.average_facebook_shares Influencer’s blog average Facebook shares
blog.articles.timestamp Match a specific creation timestamp of an article
twitter.engagement_rate Influencer’s Twitter engagement rate
twitter.followers Influencer’s Twitter followers
twitter.average_engagements Influencer’s tweets average engagements
twitter.average_favorites Influencer’s tweets average favorites
twitter.average_retweets Influencer’s tweets average retweets
twitter.tweets.timestamp Match a specific creation timestamp of a tweet
facebook.engagement_rate Influencer’s Facebook engagement rate
facebook.fans Influencer’s Facebook fans
facebook.average_engagements Influencer’s statuses average engagements
facebook.average_shares Influencer’s statuses shares
facebook.average_comments Influencer’s statuses comments
facebook.average_likes Influencer’s statuses average likes
facebook.statuses.timestamp Match a specific creation timestamp of a facebook status
pinterest.engagement_rate Influencer’s Pinterest engagement rate
pinterest.followers Influencer’s Pinterest followers
pinterest.average_repins Influencer’s pins average repins
pinterest.average_engagements Influencer’s pins average engagements
pinterest.average_likes Influencer’s pins average likes
pinterest.average_saves Influencer’s pins average saves
pinterest.average_comments Influencer’s pins average comments
pinterest.pins.timestamp Match a specific creation timestamp of a pin

Existence filter

This filter allows you to assert the results have a specific field filled or not.

It’s commonly used to assert the results have an email address.

key description
field The field / data , to apply the filter on
value with or without

Here is an example:

{
  "type": "existence",
  "field": "influencer.email",
  "value": "with"
}

All fields previously described in others filters can be used for this filter.

Geocoded filter

This filter allows you to search influencers based on their location. You have to provide a full text location and a radius.

key description
field The only value available for now is influencer.geo_coordinates
value A full text location, prefer name of city
radius the radius around the center of the location (in km)

Here is an example:

{
  "type": "geocoded",
  "field": "influencer.geo_coordinates",
  "value": "San Francisco",
  "radius": 100
}

Valid field for Geocoded filter:

field description
influencer.geo_coordinates Influencer’s coordinates

Ordering

The ordering clause allows you to order the influencer matches.

If you don’t provide any order the default one is: the relevancy of the match.

Payload format

An ordering payload is composed of two key/values:

key description
value The field / data , to apply the ordering on
direction asc or desc

Here is an example of an ordering payload:

{
  "value": "relevancy",
  "direction": "desc"
}

Ordering field

key description
relevancy Relevancy of the influencer for the search
influencer.score The score of the influencer
twitter.followers # of followers of the user on Twitter
facebook.fans # of fans of the user on Facebook
blog.alexa_rank Alexa rank of the blog
instagram.followers # of followers of the user on Instagram
youtube.followers # of subcribers of the user on Youtube
pinterest.followers # of followers of the user on Pinterest

Audience filter

This filter allows you to search through influencers with specific audience features.

key description
field The field to apply the filter on
value It should be a float value between 0 and 1 representing the percentage of the audience satisfying the clause
order One of: < less than, > greater than, = equal

Here is an example:

{
  "order": ">",
  "field": "audience.country.US",
  "value": "0.9"
}

It will search for influencers with more than 90% of their audience based in the USA.

Valid field:

field description
audience.gender.male Male audience percentage
audience.gender.female Female audience percentage
audience.age.18-24 Percentage of the Audience in age bracket: 18-24
audience.age.25-34 Percentage of the Audience in age bracket: 25-34
audience.age.35-54 Percentage of the Audience in age bracket: 35-54
audience.country.{2-letter-country-code} Percentage of the Audience based on the selected country

Influencer Searching

Influencer profile

Find influencers
POST/v1/matches{?page,per_page}

A search request is made out of three differents components:

Example URI

POST https://api.upfluence.co/v1/matches?page=&per_page=
URI Parameters
HideShow
page
number (optional) 

Page number, default: 1

per_page
number (optional) 

Number of list entries by page, default: 10, maximum: 200

Request  /v1/matches?page=1&per_page=20
HideShow
Body
{
  "ordering": {
    "value": "relevancy",
    "direction": "desc"
  },
  "filters": [
    {
      "type": "int",
      "field": "instagram.followers",
      "value": 10000,
      "order": ">",
      "negative": false
    },
    {
      "type": "geocoded",
      "field": "influencer.geo_coordinates",
      "value": "New york city",
      "radius": 100
    }
  ],
  "audience_filters": [
    {
      "order": ">",
      "field": "audience.country.US",
      "value": "0.9"
    },
    {
      "order": ">",
      "field": "audience.gender.male",
      "value": "0.9"
    }
  ],
  "criterias": [
    {
      "field": "all",
      "type": "should",
      "weight": 1,
      "value": "fashion"
    }
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "matches": [
    {
      "match_score": 12,
      "score": 25,
      "id": 1,
      "influencer_id": 42
    },
    {
      "match_score": 12,
      "score": 25,
      "id": 1,
      "influencer_id": 42
    },
    {
      "match_score": 12,
      "score": 25,
      "id": 1,
      "influencer_id": 42
    }
  ],
  "influencers": [
    {
      "id": 42,
      "name": "Influencer #1",
      "first_name": "Alexis",
      "description": "Lorem ipsum dolor...",
      "avatar_url": "https://d25re8488fs7lz.cloudfront.net/uploads/influencer/avatar/42.png",
      "country": "US",
      "address": "San Francisco, CA, USA",
      "type": "top_5",
      "community_size": 123456,
      "created_at": 1478454124,
      "updated_at": 1827402846
    },
    {
      "id": 42,
      "name": "Influencer #1",
      "first_name": "Alexis",
      "description": "Lorem ipsum dolor...",
      "avatar_url": "https://d25re8488fs7lz.cloudfront.net/uploads/influencer/avatar/42.png",
      "country": "US",
      "address": "San Francisco, CA, USA",
      "type": "top_5",
      "community_size": 123456,
      "created_at": 1478454124,
      "updated_at": 1827402846
    },
    {
      "id": 42,
      "name": "Influencer #1",
      "first_name": "Alexis",
      "description": "Lorem ipsum dolor...",
      "avatar_url": "https://d25re8488fs7lz.cloudfront.net/uploads/influencer/avatar/42.png",
      "country": "US",
      "address": "San Francisco, CA, USA",
      "type": "top_5",
      "community_size": 123456,
      "created_at": 1478454124,
      "updated_at": 1827402846
    }
  ]
}

Influencer aggregations

Get influencers stats
POST/v1/counts

A counts request is made out of four different components:

available aggregations description
country Distribution of influencer countries
language Distribution of influencer languages
reach Distribution of media
audience_age Distribution of the audience age
audience_fake Distribution between fake and real accounts in the audience
audience_gender Distribution between male and female of the audience

Example URI

POST https://api.upfluence.co/v1/counts
Request  /v1/counts
HideShow
Body
{
  "filters": [
    {
      "type": "int",
      "field": "instagram.followers",
      "value": 10000,
      "order": ">",
      "negative": false
    },
    {
      "type": "geocoded",
      "field": "influencer.geo_coordinates",
      "value": "New york city",
      "radius": 100
    }
  ],
  "audience_filters": [
    {
      "order": ">",
      "field": "audience.country.US",
      "value": "0.9"
    },
    {
      "order": ">",
      "field": "audience.gender.male",
      "value": "0.9"
    }
  ],
  "criterias": [
    {
      "field": "all",
      "type": "should",
      "weight": 1,
      "value": "fashion"
    }
  ],
  "aggregations": [
    "country",
    "audience_fake",
    "audience_age"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "count": 486,
  "aggregations": {
    "country": {
      "us": 210,
      "gb": 200,
      "br": 76
    },
    "language": {
      "en": 445,
      "fr": 43
    },
    "reach": {
      "facebook": 245,
      "instagram": 115,
      "pinterest": 105,
      "twitter": 21
    },
    "audience_age": {
      "0-17": 0.1,
      "18-24": 0.2,
      "25-34": 0.25,
      "35-54": 0.45
    },
    "audience_fake": {
      "fake": 0.1,
      "real": 0.9
    },
    "audience_gender": {
      "male": 0.45,
      "female": 0.55
    }
  }
}

Influencer profile

Influencer profile

View an influencer profile
GET/v1/influencers/{id}

Example URI

GET https://api.upfluence.co/v1/influencers/id
URI Parameters
HideShow
id
number (required) 

Id of the influencer

Request  /v1/influencers/42
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "influencer": {
    "id": 42,
    "name": "Influencer #1",
    "first_name": "Alexis",
    "email": "fake@email.com",
    "description": "Lorem ipsum dolor...",
    "avatar_url": "https://d25re8488fs7lz.cloudfront.net/uploads/influencer/avatar/42.png",
    "country": "US",
    "address": "San Francisco, CA, USA",
    "type": "top_5",
    "community_size": 123456,
    "created_at": 1478454124,
    "updated_at": 1827402846,
    "blog_id": 2,
    "facebook_id": 3,
    "twitter_id": 4,
    "instagram_id": 5,
    "youtube_id": 6,
    "pinterest_id": 7,
    "list_entry_ids": [
      17
    ]
  },
  "blogs": [
    {
      "id": 42,
      "url": "www.blogurl.com",
      "title": "Blog title",
      "description": "Blog description",
      "visits": 5678,
      "page_rank": 113,
      "alexa_rank": 94739287,
      "rss_url": "www.blogurl.com/rss",
      "category": 1,
      "articles_ids": [
        42
      ],
      "average_facebook_shares": 3029.12
    }
  ],
  "articles": [
    {
      "id": 42,
      "title": "Article title",
      "description": "Article description",
      "timestamp": 1478454124,
      "url": "www.blogurl.com/article42",
      "content": "Article content",
      "facebook_shares": 2473
    }
  ],
  "facebooks": [
    {
      "id": 109,
      "url": "https://www.facebook.com/influencer_name",
      "fans": 2000,
      "name": "Comgal",
      "bio": "This is a short description of the page",
      "status_ids": [
        42,
        102
      ],
      "engagement_rate": 2.102038,
      "category": "lifestyle",
      "subcategories": [
        "bio",
        "healthy",
        "fitness"
      ],
      "average_likes": 1364,
      "average_shares": 231,
      "average_comments": 24
    }
  ],
  "facebook_statuses": [
    {
      "id": 109,
      "text": "Hey guys, check out this bio leaf, only 49$ ! So Bio !!!",
      "likes": 9102,
      "comments": 312,
      "shares": 470,
      "timestamp": 1478454124
    }
  ],
  "list_entries": [
    {
      "id": 17,
      "list_id": 12,
      "influencer_id": 42
    }
  ],
  "list": [
    {
      "id": 12,
      "name": "Youtube Influencers"
    }
  ],
  "twitters": [
    {
      "id": 109,
      "url": "https://www.twitter.com/user",
      "name": "@influencer",
      "screen_name": "Influ Encer",
      "bio": "This is a short description of the page",
      "followers": 302,
      "tweet_ids": [
        42
      ],
      "engagement_rate": 2.102038,
      "average_retweets": 1364,
      "average_favorites": 24
    }
  ],
  "tweets": [
    {
      "id": 42,
      "content": "Post content",
      "retweets": 928,
      "favorites": 24,
      "timestamp": 1478454124
    }
  ],
  "instagrams": [
    {
      "id": 109,
      "username": "Alexis",
      "full_name": "Alexis M",
      "bio": "This is a short description of the page",
      "website": "www.example.com",
      "followers": 302,
      "media_ids": [
        42,
        43
      ],
      "story_ids": [
        51,
        52
      ],
      "engagement_rate": 2.102038,
      "average_likes": 1364,
      "average_comments": 24
    }
  ],
  "instagrams_medias": [
    {
      "id": 42,
      "text": "Need a spot? #bouldering",
      "link": "https://www.instagram.com/p/BqFuevrHlDJ/",
      "post_id": "BqFuevrHlDJ",
      "type": "picture",
      "location_name": "Mohonk Preserve",
      "likes": 928,
      "comments": 24,
      "timestamp": 1478454124
    }
  ],
  "youtubes": [
    {
      "id": 109,
      "name": "Influencer Name",
      "description": "Channel description",
      "username": "Influencer Username",
      "followers": 2000,
      "views": 430000,
      "video_ids": [
        42
      ],
      "engagement_rate": 2.102038,
      "average_views": 2310.12,
      "average_comments": 24.23,
      "average_likes": 1364.132
    }
  ],
  "youtube_videos": [
    {
      "id": 42,
      "name": "Video name",
      "description": "Video description",
      "link": "Video link",
      "views": 23453,
      "comments": 234,
      "likes": 42,
      "dislikes": 2,
      "timestamp": 1478454124
    }
  ],
  "pinterests": [
    {
      "id": 109,
      "username": "Influencer Username",
      "first_name": "Comgal",
      "last_name": "Barat",
      "bio": "This is a short description of the page",
      "followers": 2000,
      "follows": 2000,
      "pin_ids": [
        42
      ],
      "engagement_rate": 2.102038,
      "average_likes": 1364,
      "average_comments": 24,
      "average_repins": 231,
      "average_saves": 867
    }
  ],
  "pins": [
    {
      "id": 43,
      "title": "Post title",
      "description": "Post description",
      "links": "Post links",
      "likes": 928,
      "comments": 24,
      "saves": 29,
      "repins": 22,
      "timestamp": 1478454124
    }
  ]
}

Influencer creation

Ingest influencer profile
POST/v1/influencers/ingest

This endpoint allows you to find or create an influencer profile for a specific social media page.

The url argument you provide in the body of the request should be a valid URL pointing to a social media profile page. If the system can not find the social profile an error will be returned with the status code 422.

Here is some example of valid URL:

Example URI

POST https://api.upfluence.co/v1/influencers/ingest
Request  /v1/influencers/42
HideShow
Headers
Content-Type: application/json
Body
{
  "url": "https://www.instagram.com/ichigo.bk/"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "influencer_id": "42"
}

Medias per profile

Whenever you want posts/articles/medias coming from an influencer, this is where you want to look.

Facebook statuses

Fetch Facebook statuses
GET/v1/facebook_statuses{?facebook_id,limit}

Returns Facebook statuses related to a facebook_id.

Example URI

GET https://api.upfluence.co/v1/facebook_statuses?facebook_id=&limit=
URI Parameters
HideShow
facebook_id
number (required) 

Id of the facebook account

limit
number (optional) 

number of elements to return. defaut 10 / max 100

Request  /v1/facebook_statuses?facebook_id=42
Response  200
HideShow
Body
{
  "facebook_statuses": [
    {
      "id": 109,
      "text": "Hey guys, check out this bio leaf, only 49$ ! So Bio !!!",
      "likes": 9102,
      "comments": 312,
      "shares": 470,
      "timestamp": 1478454124
    }
  ]
}

Instagram medias

Fetch Instagram medias
GET/v1/instagram_medias{?instagram_id,limit}

Returns Instagram medias related to a instagram_id.

Example URI

GET https://api.upfluence.co/v1/instagram_medias?instagram_id=&limit=
URI Parameters
HideShow
instagram_id
number (required) 

Id of the instagram account

limit
number (optional) 

number of elements to return. defaut 10 / max 100

Request  /v1/instagram_medias?instagram_id=42
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "instagram_medias": [
    {
      "id": 42,
      "text": "Need a spot? #bouldering",
      "link": "https://www.instagram.com/p/BqFuevrHlDJ/",
      "post_id": "BqFuevrHlDJ",
      "type": "picture",
      "location_name": "Mohonk Preserve",
      "likes": 928,
      "comments": 24,
      "timestamp": 1478454124
    }
  ]
}

Youtube videos

Fetch youtube videos
GET/v1/youtube_videos{?youtube_id,limit}

Returns Youtube videos related to a youtube_id.

Example URI

GET https://api.upfluence.co/v1/youtube_videos?youtube_id=&limit=
URI Parameters
HideShow
youtube_id
number (required) 

Id of the youtube account

limit
number (optional) 

number of elements to return. defaut 10 / max 100

Request  /v1/youtube_videos?youtube_id=42
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "youtube_videos": [
    {
      "id": 42,
      "name": "Video name",
      "description": "Video description",
      "link": "Video link",
      "views": 23453,
      "comments": 234,
      "likes": 42,
      "dislikes": 2,
      "timestamp": 1478454124
    }
  ]
}

Blog articles

Fetch Blog articles
GET/v1/articles{?blog_id,limit}

Returns blog articles related to a blog_id.

Example URI

GET https://api.upfluence.co/v1/articles?blog_id=&limit=
URI Parameters
HideShow
blog_id
number (required) 

Id of the blog account

limit
number (optional) 

number of elements to return. defaut 10 / max 100

Request  /v1/articles?blog_id=42
Response  200
HideShow
Body
{
  "articles": [
    {
      "id": 42,
      "title": "Article title",
      "description": "Article description",
      "timestamp": 1478454124,
      "url": "www.blogurl.com/article42",
      "content": "Article content",
      "facebook_shares": 2473
    }
  ]
}

Pinterest Pins

Fetch Pins
GET/v1/pins{?pinterest_id,limit}

Returns Pins related to a pinterest_id.

Example URI

GET https://api.upfluence.co/v1/pins?pinterest_id=&limit=
URI Parameters
HideShow
pinterest_id
number (required) 

Id of the pinterest account

limit
number (optional) 

number of elements to return. defaut 10 / max 100

Request  /v1/pins?pinterest_id=42
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "pins": [
    {
      "id": 43,
      "title": "Post title",
      "description": "Post description",
      "links": "Post links",
      "likes": 928,
      "comments": 24,
      "saves": 29,
      "repins": 22,
      "timestamp": 1478454124
    }
  ]
}

Tweets

Fetch Tweets
GET/v1/tweets{?twitter_id,limit}

Returns Tweets related to a twitter_id.

Example URI

GET https://api.upfluence.co/v1/tweets?twitter_id=&limit=
URI Parameters
HideShow
twitter_id
number (required) 

Id of the twitter account

limit
number (optional) 

number of elements to return. defaut 10 / max 100

Request  /v1/tweets?twitter_id=42
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "tweets": [
    {
      "id": 42,
      "content": "Post content",
      "retweets": 928,
      "favorites": 24,
      "timestamp": 1478454124
    }
  ]
}

Media engagements

Fetch engagements over time of an influencer's social media

Fetch
GET/v1/post_stats{?blog_id,instagram_id,pinterest_id,twitter_id,facebook_id,youtube_id}

It returns the number of post and the sum of engagements generated by the social media each month. (For the last 6 months)

All the query parameters are optional but at least one must be provided.

If none is provided a response with the HTTP Status 401 will be returned

Example URI

GET https://api.upfluence.co/v1/post_stats?blog_id=&instagram_id=&pinterest_id=&twitter_id=&facebook_id=&youtube_id=
URI Parameters
HideShow
blog_id
number (optional) 

ID of the blog media

instagram_id
number (optional) 

ID of the instagram media

facebook_id
number (optional) 

ID of the facebook media

twitter_id
number (optional) 

ID of the twitter media

youtube_id
number (optional) 

ID of the youtube media

pinterest_id
number (optional) 

ID of the pinterest media

Request  /v1/post_stats?instagram_id=42
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "post_stats": [
    {
      "month": 11,
      "year": 17,
      "posts": 10,
      "engagements": 7890
    }
  ]
}

List management

View the lists belonging to the user

View the lists belonging to the user
GET/v1/lists

Example URI

GET https://api.upfluence.co/v1/lists
Request  /v1/lists/
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "lists": [
    {
      "id": 12,
      "name": "Youtube Influencers",
      "count": 3
    }
  ]
}

Create a list

Create a list
POST/v1/lists

Example URI

POST https://api.upfluence.co/v1/lists
Request  /v1/lists/
HideShow
Headers
Content-Type: application/json
Body
{
  "list": {
    "name": "Youtube Influencers"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "list": [
    {
      "id": 12,
      "name": "Youtube Influencers",
      "count": 3
    }
  ]
}

List item

View the list belonging to the user
GET/v1/lists/{id}

Example URI

GET https://api.upfluence.co/v1/lists/id
URI Parameters
HideShow
id
number (required) 

Id of the list

Request  /v1/lists/12
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "list": [
    {
      "id": 12,
      "name": "Youtube Influencers",
      "count": 3
    }
  ]
}

Update a list
PUT/v1/lists/{id}

Example URI

PUT https://api.upfluence.co/v1/lists/id
URI Parameters
HideShow
id
number (required) 

Id of the list

Request  /v1/lists/12
HideShow
Body
{
  "list": {
    "name": "New Name"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "list": [
    {
      "id": 12,
      "name": "New Name",
      "count": 3
    }
  ]
}

Delete a list
DELETE/v1/lists/{id}

Example URI

DELETE https://api.upfluence.co/v1/lists/id
URI Parameters
HideShow
id
number (required) 

Id of the list

Request  /v1/lists/12
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "OK"
}

List entries manangement

View all list entries

View all list entries
GET/v1/list_entries/{?list_id,page,per_page}

Example URI

GET https://api.upfluence.co/v1/list_entries/?list_id=&page=&per_page=
URI Parameters
HideShow
list_id
number (required) 

Id of a list

page
number (optional) 

Page number, default: 1

per_page
number (optional) 

Number of list entries by page, default: 10

Request  /v1/list_entries/?list_id=12
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "influencers": [
    {
      "id": 42,
      "name": "Influencer #1",
      "first_name": "Alexis",
      "description": "Lorem ipsum dolor...",
      "avatar_url": "https://d25re8488fs7lz.cloudfront.net/uploads/influencer/avatar/42.png",
      "country": "US",
      "address": "San Francisco, CA, USA",
      "type": "top_5",
      "community_size": 123456,
      "created_at": 1478454124,
      "updated_at": 1827402846
    }
  ],
  "list_entries": [
    {
      "id": 17,
      "list_id": 12,
      "influencer_id": 42
    }
  ],
  "list": [
    {
      "id": 12,
      "name": "Youtube Influencers"
    }
  ],
  "meta": {
    "total": 1,
    "total_pages": 1
  }
}

Add an influencer to a list

Add an influencer to a list
POST/v1/list_entries

Example URI

POST https://api.upfluence.co/v1/list_entries
Request  /v1/list_entries/
HideShow
Body
{
  "list_entry": {
    "list_id": 12,
    "influencer_id": 42
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "list_entry": {
    "id": 17,
    "list_id": 12,
    "influencer_id": 42
  },
  "lists": [
    {
      "id": 12,
      "name": "Youtube Influencers"
    }
  ]
}

List the influencers belonging to a list

View a specific entry
GET/v1/list_entries/{id}

Example URI

GET https://api.upfluence.co/v1/list_entries/id
URI Parameters
HideShow
id
number (required) 

Id of the list

Request  /v1/list_entries/17
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "list_entry": {
    "id": 17,
    "list_id": 12,
    "influencer_id": 42
  },
  "lists": [
    {
      "id": 12,
      "name": "Youtube Influencers"
    }
  ]
}

Delete an influencer from a list
DELETE/v1/list_entries/{id}

Example URI

DELETE https://api.upfluence.co/v1/list_entries/id
URI Parameters
HideShow
id
number (required) 

Id of the list

Request  /v1/list_entries/17
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "OK"
}

Audience data

This endpoint responds with multiple aggregations:

  • Typology: Real / Fake ( fake_account )

  • Gender ( audience_gender )

  • Age ( bracket ) ( audience_age )

  • Geolocation per country ( audience_city )

    • Each country is represented by their two letter code (i.e. France is FR)
  • Geolocation per state ( audience_state )

  • Geolocation per city ( audience_country )

For each of those aggregation keys the value linked will be composed of:

  • The number of profile analyzed ( total )

  • The values extracted from those profiles ( values )

Fetch audience data

Fetch audience data
GET/v1/audience?influencer_id

Example URI

GET https://api.upfluence.co/v1/audience?influencer_id
URI Parameters
HideShow
influencer_id
number (required) 

ID of the influencer

Request  /v1/audience?influencer_id=2854431
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "fake_account": {
    "total": 4567,
    "values": {
      "real": "0.9",
      "fake": "0.1"
    }
  },
  "audience_gender": {
    "total": 4567,
    "values": {
      "male": "0.9",
      "female": "0.1"
    }
  },
  "...": "Rest of the aggregation"
}