Facebook Field Data API
The Field Data API's purpose is to provide an electronic means for field partners to upload survey data for field operations.
This article pre-supposes that the user has gone through the process in the BDS Developer Onboarding article. Documentation of the Field Data API is accessible online for each of the Field Data methods. This article is a supplement to it to provide details and use cases.
Endpoints
Stage - https://bdsmktg.azure-api.net/FieldData
Endpoint used for testing the API
Production - https://bdssolutions.azure-api.net/FieldData
Endpoint used for live production work.
API Methods
Authenticate
Vendors use the API Authentication Credentials emailed in the onboarding process in the authentication step.
- Username, Password
- Subscription Key
Calling this method of the API with the vendor credentials returns an authentication token. The returned GUID will need to be used in subsequent calls to the API.
Stage - https://bdsmktg.azure-api.net/FieldData/AuthenticateVendor
Prod - https://bdssolutions.azure-api.net/FieldData/AuthenticateVendor
Business Rules
- The authentication token remains active for 3 hours after initial call.
Http Request
Code samples for other formats are available on the Developer Portal
Return
The return is a GUID (Globally Unique Identifier). A GUID need to be used in all subsequent calls to the API. The token remains active for 3 hours after initial creation.
02535BF0-6FB8-454A-B36A-81F8B0A8EF69
Use case - Create Visit - Post Visit
When vendor company completes a visit for the Facebook field program they will use the Post Visit method of the Field Data API to provide the data collected during the visit to BDS.
Request URL
Stage - https://bdsmktg.azure-api.net/FieldData/PostVisit
Prod - https://bdssolutions.azure-api.net/FieldData/PostVisit
Business rules
- The following fields are required:
- FacebookStoreID
- RetailerName
- RetailerAddressLine1
- RetailerCity
- RetailerStateProvince
- RetailerCountryCode - ISO 3166-1 alpha-3 code
- Example: USA
- RetailerPostalCode
- PartnerVisitID
- VisitDateTime
- VisitDuration
- FacebookStoreID is validated by VendorID. This means vendors must be authorized to use specific FacebookStoreIDs. This is managed by the BDS Hackers Guide team.
- The Answers collection must be a non zero array
- For each Vendor the Facebook Questions are validated (by date) using the submitted Visit Date for active status
- VisitDateTime cannot be greater than 24 hours of current date/time
- VisitDateTime is in date-time-offset standard format: yyyy-MM-ddTHH:mm:ss -HH:mm or yyyy-MM-ddTHH:mm:ss +HH:mm
- Format Example: "2020-07-19T08:00:00 -07:00"
Answers collection
The following fields are required:
- FacebookQuestionChoiceID
- Integer
- Unique identifier of a valid question choice
- FacebookQuestionID
- Integer
- A list of valid QuestionIDs is supplied to each vendor during onboarding by the Account Team
- Facebook Questions are active for a start and end date. These questions could be ended during the program making them no longer valid for submittal
- A question cannot be submitted if the question is no longer active
- The Facebook team will provide notice for question changes
- FacebookQuestionText
- String
- Is the text of the question that matches the supplied Facebook Question(s)
- Answer
- String
- Must be a non-empty string
- If the question has multiple choices the answer text must match one of the supplied choice text
- Display Type
- String
- Must be a non-empty string
Body Request
{ "visit": {
"FacebookStoreID": "BGRFR000000F007", "PartnerVisitID": "5001", "RetailerName": "Best Buy", "RetailerStoreNumber": "100", "RetailerAddressLine1": "123 Main St", "RetailerAddressLine2": "Unit 12", "RetailerCity": "Hometown", "RetailerStateProvince": "NY", "RetailerCountryCode": "USA", "RetailerPostalCode": "00385 ", "RetailerLatitude": "41.951894", "RetailerLongitude": "-70.716924", "VisitDateTime": "2020-07-19T08:00:00-07:00", "VisitDuration": 35, "Answers": [{ "Answer": "Answer value", "DisplayType": "Endcap",
"FacebookQuestionChoiceID": 4942, "FacebookQuestionID": 100, "FacebookQuestionText": "Did you do the thing?" }, { "Answer": "Answer value", "DisplayType": "Endcap", "FacebookQuestionID": 200, "FacebookQuestionText": "Why not?" }, { "Answer": "Appearance", "DisplayType": "Countertop",
"FacebookQuestionChoiceID": 5652, "FacebookQuestionID": 301, "FacebookQuestionText": "What are the top features or reasons that influenced consumers' purchasing decisions? (choose up to 3)" }, { "Answer": "Comfort", "DisplayType": "Countertop", "FacebookQuestionChoiceID": 5653,
"FacebookQuestionID": 301, "FacebookQuestionText": "What are the top features or reasons that influenced consumers' purchasing decisions? (choose up to 3)" } ] }, "token": "dba971d3-761d-4dff-96c6-2763b971aefb" }
Return
The return is the FacebookVisitID or an error message
"1000"
Use case - Update Visit - Update Visit
If a vendor company needs to make updates to any visits already posted then the Update Visit method is used.
Request URL
Stage - https://bdsmktg.azure-api.net/FieldData/UpdateVisit
Prod - https://bdssolutions.azure-api.net/FieldData/UpdateVisit
Business rules
- The following fields are required:
- FacebookStoreID
- FacebookVisitID
- PartnerVisitID
- RetailerName
- RetailerAddressLine1
- RetailerCity
- RetailerStateProvince
- RetailerCountryCode - ISO 3166-1 alpha-3 code
- Example: USA
- RetailerPostalCode
- PartnerVisitID
- VisitDateTime
- VisitDuration
- FacebookStoreID is validated by VendorID. This means vendors must be authorized to use specific FacebookStoreIDs. This is managed by the BDS Hackers Guide team.
- VisitDateTime cannot be greater than the current date/time plus 24 hours.
- VisitDateTime is in date-time-offset standard format: yyyy-MM-ddTHH:mm:ss -HH:mm or yyyy-MM-ddTHH:mm:ss +HH:mm
- Format Example: "2020-07-19T08:00:00 -07:00"
- The Answers collection must be a non zero array
- For the Vendor, was the "Facebook Question ID" valid (by date) on the submitted Visit Date
- For number answer types. is the answer match a valid number.
- For single/multi answer types, does the provided answer match the choices for that Question, matched textually.
Updates
- Updates are performed sending the FacebookVisitID and PartnerVisitID in addition to required fields.
- The answers collection in the update post replaces the previous answers.
Body Request
{ "visit": {
"FacebookStoreID": "BGRFR000000F007", "FacebookVisitID": 1000, "PartnerVisitID": "5001", "RetailerName": "Best Buy", "RetailerStoreNumber": "100", "RetailerAddressLine1": "123 Main St", "RetailerAddressLine2": "Unit 12", "RetailerCity": "Hometown", "RetailerStateProvince": "NY", "RetailerCountryCode": "USA", "RetailerPostalCode": "00385 ", "RetailerLatitude": "41.951894", "RetailerLongitude": "-70.716924", "VisitDateTime": "2020-07-19T08:00:00-07:00", "VisitDuration": 35, "Answers": [{ "Answer": "Yes", "DisplayType": "Endcap",
"FacebookQuestionChoiceID": 4962, "FacebookQuestionID": 100, "FacebookQuestionText": "Are the dummy product boxes installed on the Oculus display?" }, { "Answer": "12", "DisplayType": "Endcap", "FacebookQuestionID": 200, "FacebookQuestionText": "How many portal tv sales did you make in store today?" },
{
"Answer": "Appearance",
"DisplayType": "Countertop",
"FacebookQuestionChoiceID": 5652,
"FacebookQuestionID": 302,
"FacebookQuestionText": "What are the top features that influenced a purchase?"
},
{
"Answer": "Quality",
"DisplayType": "Countertop",
"FacebookQuestionChoiceID": 5651,
"FacebookQuestionID": 302,
"FacebookQuestionText": "What are the top features that influenced a purchase?
} ] }, "token": "dba971d3-761d-4dff-96c6-2763b971aefb" }
Return
The return is the FacebookVisitID or an error message
"1000"
Use case - Delete Visit - Delete Visit
When a vendor company needs to delete any visits already posted the Delete Visit method is used. This method deletes the entire visit including answers.
Stage - https://bdsmktg.azure-api.net/FieldData/DeleteVisit/{token}/{facebookVisitID}
Prod - https://bdssolutions.azure-api.net/FieldData/DeleteVisit/{token}/{facebookVisitID}
Parameters
- Token
- FacebookVisitID
Return
The return is Success or an error message
"Success"
Use case - Lookup/Listing visits - Get Visit(s)
When a vendor company wants to view previously posted visits the Get Visit(s) methods are used.
Get Visit by Partner Visit ID
Returns a single visit and all questions and answers using the vendors visit ID.
Parameters
- Authentication Token
- PartnerVisitID
Return
{ "Message": "", "Visits": [{ "Answers": [{ "Answer": "Retail - In Store", "DisplayType": "Endcap",
"FacebookQuestionChoiceID": 7851, "FacebookQuestionID": 1527, "FacebookQuestionText": "What type of Oculus event are you supporting?" }, { "Answer": "Google Nest", "DisplayType": "Countertop",
"FacebookQuestionChoiceID": 9872 "FacebookQuestionID": 1534, "FacebookQuestionText": "Which of the following competitive AR\/VR brands were present at the Oculus event?" },
{
"Answer": "Amazon Echo Show",
"DisplayType": "Countertop",
"FacebookQuestionChoiceID": 9873
"FacebookQuestionID": 1534,
"FacebookQuestionText": "Which of the following competitive AR\/VR brands were present at the Oculus event?"
},
{
"Answer": "204"
"DisplayType": "Endcap"
"FacebookQuestionID": 5698,
"FacebookQuestionText": "How many people stopped at the kiosk?"
}
],
"FacebookStoreID": "BGRFR000000F007",
"FacebookVisitID": 1001, "PartnerVisitID": "5001", "RetailerAddressLine1": "123 Main St", "RetailerAddressLine2": "Unit 12", "RetailerCity": "Hometown", "RetailerCountryCode": "USA", "RetailerName": "Best Buy", "RetailerPostalCode": "00385 ", "RetailerLatitude": "41.951894", "RetailerLongitude": "-70.716924", "RetailerStateProvince": "AL", "RetailerStoreNumber": "100", "VisitDateTime": "2020-07-19 15:00:00Z", "VisitDuration": 35 }] }
Get Visit by Visit ID
Returns a single visit and all questions and answers using the Facebook Visit ID.
Parameters
- Authentication Token
- FacebookVisitID
Return
{ "Message": "", "Visits": [{ "Answers": [{ "Answer": "Retail - In Store", "DisplayType": "Endcap",
"FacebookQuestionChoiceID": 7851, "FacebookQuestionID": 1527, "FacebookQuestionText": "What type of Oculus event are you supporting?" },
{
"Answer": "985",
"DisplayType": "Countertop",
"FacebookQuestionID": 2658,
"FacebookQuestionText": "How many people attended the event?"
},
{ "Answer": "Google Nest", "DisplayType": "Endcap",
"FacebookQuestionChoiceID": 5652, "FacebookQuestionID": 1534, "FacebookQuestionText": "Which of the following competitive AR\/VR brands were present at the Oculus event?" },
{
"Answer": "Amazon Echo Show",
"DisplayType": "Endcap",
"FacebookQuestionChoiceID": 5653,
"FacebookQuestionID": 1534,
"FacebookQuestionText": "Which of the following competitive AR\/VR brands were present at the Oculus event?"
}
],
"FacebookStoreID": "BGRFR000000F007", "FacebookVisitID": 1001, "PartnerVisitID": "5001", "RetailerAddressLine1": "123 Main St", "RetailerAddressLine2": "Unit 12", "RetailerCity": "Hometown", "RetailerCountryCode": "USA", "RetailerName": "Best Buy", "RetailerPostalCode": "00385 ", "RetailerLatitude": "41.951894", "RetailerLongitude": "-70.716924", "RetailerStateProvince": "AL", "RetailerStoreNumber": "100", "VisitDateTime": "2020-07-19 15:00:00Z", "VisitDuration": 35 }] }
Get Visits
Returns a list of visits and all questions and answers using where the visit date time is between the start date and end date.
Parameters
- Authentication Token
- Startdate in the ISO8601 format: yyyy-MM-ddTHH:mm:ss -HH:mm or yyyy-MM-ddTHH:mm:ss +HH:mm
- Format Example: "2020-07-19T08:00:00 -07:00"
- Enddate in the ISO8601 format: yyyy-MM-ddTHH:mm:ss -HH:mm or yyyy-MM-ddTHH:mm:ss +HH:mm
- Format Example: "2020-07-19T08:00:00 -07:00"
Return
{ "Message": "", "Visits": [{ "Answers": [{ "Answer": "Yes", "DisplayType": "Endcap",
"FacebookQuestionChoiceID": 4942, "FacebookQuestionID": 100, "FacebookQuestionText": "Are the dummy product boxes installed on the Oculus Display?"," }, { "Answer": "12", "DisplayType": "Countertop", "FacebookQuestionID": 200, "FacebookQuestionText": "How many portal tv sales did you make in store today?" },
{
"Answer": "Appearance",
"DisplayType": "Endcap",
"FacebookQuestionChoiceID": 5652,
"FacebookQuestionID": 301,
"FacebookQuestionText": "What are the top features or reasons that influenced consumers' purhasing decisions? (choose up to 3)"
},
{
"Answer": "Comfort",
"DisplayType": "Endcap",
"FacebookQuestionChoiceID": 5652,
"FacebookQuestionID"" 301,
"FacebookQuestionText": "What are the top features or reasons that influenced consumers' purchasing decisions? (choose up to 3)"
} ],
"FacebookStoreID": "BGRFR000000F007",
"FacebookVisitID": 1242, "PartnerVisitID": "5001", "RetailerAddressLine1": "123 Main St", "RetailerAddressLine2": "Unit 12", "RetailerCity": "Hometown", "RetailerCountryCode": "USA", "RetailerName": "Best Buy", "RetailerPostalCode": "00385 ", "RetailerLatitude": "41.951894", "RetailerLongitude": "-70.716924", "RetailerStateProvince": "NY", "RetailerStoreNumber": "100", "VisitDateTime": "2020-07-19 15:00:00Z", "VisitDuration": 30 }, { "Answers": [{ "Answer": "Yes", "DisplayType": "Endcap",
"FacebookQuestionChoiceID": 8795, "FacebookQuestionID": 10011, "FacebookQuestionText": "Did you do the thing?" }, { "Answer": "Answer value", "DisplayType": "Countertop", "FacebookQuestionChoiceID": 4125,
"FacebookQuestionID": 300, "FacebookQuestionText": "Why not?" },
{
"Answer": "15",
"DisplayType"": "Countertop",
"FacebookQuestionID": 236,
"FacebookQuestionText": "How many customers did you speak to today?"
},
{
"Answer": "Quality",
"DisplayType" : "Endcap",
"FacebookQuestionChoiceID": 3156,
"FacebookQuestionID": 203,
"FacebookQuestionText": "What are the top reasons for purchasing?"
},
{
"Answer": "Price",
"DisplayType": "Endcap",
"FacebookQuestionChoiceID": 3157,
"FacebookQuestionID": 203,
"FacebookQuestionText": "What are the top reasons for purchasing?"
} ],
"FacebookStoreID": "BGRFR000000F007",
"FacebookVisitID": 1243, "PartnerVisitID": "Test_II", "RepPositionCode": "UNK", "RetailerAddressLine1": "111 Main St", "RetailerAddressLine2": "Unit 12", "RetailerCity": "Hometown", "RetailerCountryCode": "USA", "RetailerName": "Best Buy", "RetailerPostalCode": "00385 ", "RetailerStateProvince": "NAY", "RetailerStoreNumber": "100", "VisitDateTime": "2020-07-19 15:00:00Z", "VisitDuration": 35, "VisitTypeCode": "S" } ] }
Comments
0 comments
Please sign in to leave a comment.