For Facebook authors, the SMM APIs and Analytics Reports use Facebook’s Page-Scoped User IDs (PSIDs) as the ID for each author. It is a unique ID for an author interacting with a specific Facebook page.

If someone interacts with multiple Facebook pages, they will have a different PSIDs for each page. And if those different pages are all part of the same Facebook Business Manage Account, Khoros will automatically associate them to the same author in our system.

Remember that a PSID is associated with a page and author, so if you have a PSID you also need to know the page that it is for.

Why care about PSIDs?

Because the PSID is the same for a user across all Facebook applications that you authorize, you can correlate users between these different applications.

For example, if you offer your customers the ability to login to your website using their Facebook account, you can get their PSID and store it on your customer record. With that PSID, you can query Khoros to get information about that author's conversation and update information about that person.
If you export analytics data from Khoros, authors include the PSID so you can join it to that same person’s interaction with you from other Facebook applications.

Find an author’s PSIDs with the API

The following Conversation, Author, and Analytics Reports APIs return all the PSIDs (and the respective page IDs) associated with an Author in their response payloads.

👍

Tip

We recommend finding an author’s PSIDs using the Conversation API because this is the simplest path with the information you most likely have -- a conversation ID. We’ll show an example for retrieving a PSID with the Conversation API later in this guide.

Khoros generalizes ID associations into a concept called scopedIds, where the scope field indicates the ID's scope. In the case of PSID's the scope is PAGE. That this time, PAGE is the only supported value for scope.

This example of a scopedIds object the response provides the author’s PSID for each Facebook page.

"scopedIds":[  
    {  
        "id":"2031810236844413",
        "instance":"354241721305178",
        "scope":"PAGE"
    }
]

scopedIds Object Fields

Conversation APIs that return PSIDs

GET /api/v2/conversations/displayIds/displayNumber
GET /api/v2/conversations/lswUuid

In the details for a Facebook conversation returned from the Conversation API, you’ll see an author object that looks something like the one below. In this example, we have a single author with two PSIDs (this means that the author has interacted with 2 pages that are part of the same Business Manager account).

"author": {
    "scopedIds": [
        {
            "id": "1248731485254475",
            "instance": "247834501907136",
            "scope": "PAGE"
        },
        
            "id": "1332864636770699",
            "instance": "1009123765820374",
            "scope": "PAGE"
        }
    ],
    "lswUuid": "3b167fbb-00e6-456f-9867-7930277b2604"
}

Author APIs that return PSIDs

• GET api/v2/authors/lswUuid

When the Author API returns a Facebook author, the API returns the author’s PSIDs in the scopedIds object.

{  
  "status":"success",
  "data":[  
    {  
      ...
      "handles":{  
        "facebook":[  
          {  
            "@class":"FacebookSpecificAuthorData",
            "lswUuid":"c06b2ba0-2ce6-11e9-86b4-0242ac110006",
            "displayNumber":100583894,
            "profileUrl":"",
            "name":"Dharla Funnechs",
            "scopedIds":[  
              {  
                "id":"2031810236844413",
                "instance":"354241721305178",
                "scope":"PAGE"
              }
            ],
            ...
          }
        ]
      },
      ...
    }
  ]
}

Analytics Reports APIs that return PSIDs

POST /api/public/reports/report/report_type where report_type is the report to run

The following Analytics Reports display the PSID:

• incoming_post (Raw Incoming Post Export) - External Author Handle ID field
• author (Raw Author Export) - Facebook UID(s) field
• combined (Raw Combined Export) - External ID field

curl -u [USERNAME]:[PASSWORD] -XPOST \ 'https://analytics-api.app.lithium.com/api/public/reports/report/incoming_post?startTime=1435167000000&endTime=1435167900000&timezoneOffset=-18000000&locale=en_US&companyKey=[COMPANY KEY]'

The format for Facebook authors is <pageId1>:<psid1>,<pageId2>:<psid2>,...

Here is a sample of what the data looks like in the Raw Incoming Post Export in the External Author Handle ID column:

194872147362946:1338894862874836,1738728279712791:2016683335066626