Instagram Content Publishing API (now supports Pinterest too)

Documentation

Authentication
Please locate your Client Id and Client Secret located in API section of your account.
Sample Apps
While you can easily test this API using CURL or any other REST API client, we are in the process of creating starter apps in several languages.

Rate Limiting
All endpoints, except for publishing, have a rate limit of 10 requests per minute. Each endpoint is rate limited separately. Please observe X-Rate-Limit and X-Rate-Limit-Remaining headers which will inform you of remaining rate limit for that resource. For publishing end point the rate limit per 10 posts per profiles per hour.

If an application abuses the rate limits, it will be blacklisted.

These rate limits should work for the majority of projects. If you feel you have legitimate requirements and these rate limits are preventing you from accomplishing them - please send us a note.
Access Expiration
When your users connect their Instagram Business Profile, they authorize Concrete Social to have such access. By default, this access will only last 90 days. If your users access your application regularly you can ensure that this access never expires by including our script and serve it to your customers as often as possible.

<script src="https://concretesocial.io/activity.js"></script>
Authorize
GET: https://concretesocial.io/1.0/authorize
Initiates authorization flow. This link will direct the user to our system and subsequently to Facebook to authorize their account.


Rate limit: none.
Parameter Description
client_id your client id
redirect_url url encoded location where we will redirect back after the authorization process completes
type instagram (default) or pinterest

Example Request

https://concretesocial.io/1.0/authorize?client_id=dd9f3f879e3dbb7b62004b4966250881&redirect_url=http://yoursite.com/callback

Example Response

http://yoursite.com/callback?code=5c291ee4de8d39e7f22866cd                       

Activate profile
POST: https://concretesocial.io/1.0/profiles
Now that you have received instagram business profiles from authorization flow, you can let your users select the once they would like to connect and use profile ids to add them to your account.


Rate limit: none.
Parameter Description
client_id your client id
client_secret your client secret
ids Comma delimited list of selected account ids

Example Request (using curl)

curl --request POST \
  --url https://concretesocial.io/1.0/profiles \
  --data '{"client_id" : "dd9f3f879e3dbb7b62004b4966250881", 
              "client_secret" : "cmVhZG1ldmlzaXRvcjozMjl4MTlXcG5BelpGb2hh", 
              "ids":"5c29196d8c93b005087765a6,5c29196d8c93b005087765a8"}'                     

Example Response

{
  "profiles": [
      '5c29196d8c93b005087765a6',
      '5c29196d8c93b005087765a8'
  ]
}

Publish media (image or video)
POST: https://concretesocial.io/1.0/publish
Rate limit: 10 posts per profile per hour.
IMPORTANT Please be sure to set your request timeout to a value that is substantially long. Video posts, in particular, may take several minutes to post.
Parameter Description
caption A caption for the photo. Like the app, you can include hashtags (e.g., #crazywildebeest) and usernames of Instagram Users (e.g., @natgeo). @Mentioned Users will receive a notification when you publish the media object container.
media_type Type of media you are posting. Supported values are image or video. Please review image and video specifications.
media_url The path to the photo or video. We will cURL your photo using the passed in URL so it must be on a public server.
profiles List of profile ids where this post will be published. You can find profile id on the profiles page or using an /profiles endpoint. If posting to Pinterest please include a board id: profile_id:board_id (i.e. 5c66f28b0c4edb5783faa39a:486881478404942408)
location_id (instagram only, optional) The ID of a Places Graph Place location you want to tag the photo with. Use the Places search to discover Place IDs.
user_tags (instagram only, optional) An array of public usernames and x/y coordinates for any public Instagram Users who you want to tag in the photo. The array must be formatted in JSON and contain a username, x, and y, property, such as [{username:'natgeo',x:0.5,y:1.0}]. x and y values must be float numbers that originate from the top-left of the image, with a range of 0.0–1.0 Tagged users will receive a notification when you publish the media container.
comment (instagram only, optional) Follow up comment that will be added to the main publication. Great place to put in your extra hashtags.

Media Specifications

  • Image
    • Maximum file size: 8MB
    • Aspect ratio: Must be within a 4:5 to 1.91:1 range
    • Minimum resolution: 150x150 (lower resolutions will be scaled up to the minimum)
    • Maximum resolution: 1920x1080 (higher resolutions will be scaled down to the maximum)
    • Formats: JPEG, PNG, BMP, and non-animated GIFs
  • Video
    • Container: MOV or MP4 (MPEG-4 Part 14), no edit lists, moov atom at the front of the file.
    • Audio codec: AAC, 48khz sample rate maximum, 1 or 2 channels (mono or stereo).
    • Video codec: HEVC or H264, progressive scan, closed GOP, 4:2:0 chroma subsampling.
    • Frame rate: 23-60 FPS.
    • Picture size:
      • Maximum columns (horizontal pixels): 1920
      • Minimum aspect ratio [cols / rows]: 4 / 5
      • Maximum aspect ratio [cols / rows]: 16 / 9
    • Bitrate: VBR, 5Mbps maximum
    • Duration: 60 seconds maximum, 3 seconds minimum
    • File size: 100MB maximum

Sample Request

{
  "caption" : "My first instagram post",
  "media_type" : "image",
  "media_url" : "https://cdn.pixabay.com/photo/2018/10/28/16/11/landscape-3779159_1280.jpg",
  "profiles": ["5c21013a8c93b0050877659d"],
  "comment" : "#nature #amazing",
  "client_id" : "dd9f3f879e3dbb7b62004b4966250881", 
  "client_secret" : "cmVhZG1ldmlzaXRvcjozMjl4MTlXcG5BelpGb2hh"
}

Success Response

{
  "request_id": "5c2103084e22e773b48a3eb0",
  "result": [
    {
      "profile": "5c21013a8c93b0050877659d",
      "media": "https://www.instagram.com/p/Brxqt0ED3WW/"
    }
  ]
}

Failure Response

{
  "request_id": "5c210d2aadc32878b3f8d03f",
  "result": [
    {
      "profile": "5c21013a8c93b0050877659d",
      "response": {
        "error": {
          "message": "The aspect ratio is not supported.",
          "error_user_title": "Invalid Aspect Ratio",
          "error_user_msg": "The submitted image with aspect ratio 2376/1020 cannot be published. Please submit an image with a valid aspect ratio."
        }
      }
    }
  ]
}

CURL Example

curl --request POST \
  --url https://concretesocial.io/1.0/publish \
  --data '{ "client_id" : "dd9f3f879e3dbb7b62004b4966250881", 
            "client_secret" : "cmVhZG1ldmlzaXRvcjozMjl4MTlXcG5BelpGb2hh", 
            "caption":"Wonderful",
            "media_type" : "image",
            "media_url" : "https://cdn.pixabay.com/photo/2018/10/28/16/11/landscape-3779159_1280.jpg", 
            "profiles" : ['5c21013a8c93b0050877659d'], "comment" : "extra comment"}'                    

List connected profiles
GET: https://concretesocial.io/1.0/profiles
Retrieves active profiles

Rate limit: 30 requests per minute.
Parameter Description
id (optional) retrieves specific profile based on internal id
page (optional) to help with retrieval large number of profiles, each request returns 100 results, by specifying page parameter as 2 you will get profiles 101-200.

Response

[
  {
    "id": "17841401478355432",
    "followers_count": 9,
    "follows_count": 10,
    "media_count": 93,
    "custom_id" : 'your_custom_id',
    "user": "Anna"
  },
  {
    "id": "17841401478355987",
    "followers_count": 11121,
    "follows_count": 195,
    "media_count": 48,
    "user": "Lynn"
  },
  {
    "id": "12241401478355333",
    "followers_count": 655,
    "follows_count": 130,
    "media_count": 34,
    "website": "https://angel.co",
    "user": "Roger"
  }
]

CURL Example

curl --request GET \
  --url https://concretesocial.io/1.0/profiles?custom_id=your_custom_id&client_id=dd9f3f879e3dbb7b62004b4966250881&client_secret=9bbd2efffd5b9b4b88a6a079c8e86059

Deauthorization
It is possible for a Facebook user to remove Concrete Social from the list of business integrations (authorized apps). If and when this happens, we can send a webhook notification to your app. It will allow your app to quickly react to this a notify the user that they need to reconnect their profiles. If a user does remove Concrete Social - access is lost and posts will start to fail.

List of business integration is located in Page Settings - Business Integrations:



You can register your deauthorization url by going to console.

Sample Notification. Note that you receive a list of impacted profiles.

{
    "profiles": ['17841401478355432', '17841401478355433']
 }
Get active profile
GET: https://concretesocial.io/1.0/profiles/:id
Retrieves active profile. Please note 'access' field. This tells you if we still have good access to this profile. If loose access - you will need to prompt your user to reconnect it. You can also observe failures on published posts and allow your users to reconnect profiles.

Rate limit: 1 request per profile per hour.
Parameter Description
id profile id

Response

{
    "id": "17841401478355432",
    "followers_count": 9,
    "follows_count": 10,
    "media_count": 93,
    "custom_id" : 'your_custom_id',
    "user": "Anna",
    "status" : true,
 }

CURL Example

curl --request GET \
  --url https://concretesocial.io/1.0/profiles/17841401478355432?client_id=dd9f3f879e3dbb7b62004b4966250881&client_secret=9bbd2efffd5b9b4b88a6a079c8e86059

Update active profile
POST: https://concretesocial.io/1.0/profiles/:id
Updates custom_id field of connected profile
Parameter Description
custom_id new value of custom_id field

Response

{
    "id": "17841401478355432",
    "followers_count": 9,
    "follows_count": 10,
    "media_count": 93,
    "custom_id" : 'your_custom_id',
    "user": "Anna"
 }

CURL Example

curl --request POST \
  --url https://concretesocial.io/1.0/profiles/17841401478355432   
  --data '{"custom_id":"new value", 
              "client_id : "dd9f3f879e3dbb7b62004b4966250881", 
              "client_secret" : "9bbd2efffd5b9b4b88a6a079c8e86059"}'

Places search
GET: https://concretesocial.io/1.0/search/place
Search for millions of places worldwide. Retrieved Place ID can then be used as location_id parameter when publishing.

Rate limit: 10 requests per minute.
Parameter Description
profile_id ID for the profile that you are performing this search for.
q The name of the place to search for. If you don't specify a name to search for, then you must specify the center of the search. In that case, the response will contain places that are around the given location.
center The coordinates for the center of the search, in the format: [latitude],[longitude]; e.g., 140.7307,-73.9918. If you don't specify this parameter, then q is required, and the places in the response will not be associated with any particular location.
distance The maximum distance in meters from the center. This parameter can only be used in conjunction with center.

Response

{
  "data": [
    {
      "name": "Cafe Nadery - Manhattan",
      "picture": "https://scontent.xx.fbcdn.net/v/t1.0-1/c0.5.50.50/p50x50/10649901_725675507526285_870344638622809210_n.png?oh=ba0aa86504dd6f4bbc22a2f38283a585&oe=5890406D",
      "id": "460770554016783"
    },
    {
      "name": "Cafe Mogador",
      "picture": "https://scontent.xx.fbcdn.net/v/t1.0-1/c68.15.185.185/s50x50/602492_441893165845839_267814448_n.jpg?oh=fd0f4c6548b25ca4f664612edfb35571&oe=58C214AF",
      "id": "111724322196060"
    },
    {
      "name": "Cafe Orlin",
      "picture": "https://scontent.xx.fbcdn.net/v/t1.0-1/c7.0.50.50/p50x50/943881_1097275670291612_7819187236926166576_n.jpg?oh=aad1628ab28315485b1d8ac91503cdc2&oe=589522C4",
      "id": "147652718587250"
    }
}

CURL Example

curl --request GET \
  --url https://concretesocial.io/1.0/search/place&q=cafe
           ¢er=40.7304,-73.9921
           &distance=1000'
           &profile_id=17841401478355432'   
           &client_id=dd9f3f879e3dbb7b62004b4966250881
           &client_secret=9bbd2efffd5b9b4b88a6a079c8e86059