Vendasta Social REST API
Social AI product API for connected social profiles and messages on a business location. Published as OpenAPI 3.1.0. Scope-gated with the `social` OAuth2 scope.
OpenAPI Specification
openapi: 3.1.0
info:
title: Social
version: Evergreen
description: These APIs allow users to use Vendasta's social capabilities. All the endpoints require either the `social` or `business` scopes to be accessed.
servers:
- url: 'https://prod.apigateway.co/products/social'
description: Production
- url: 'https://demo.apigateway.co/products/social'
description: Demo
- url: 'http://localhost:3000/products/social'
description: Local
- description: Localhost
url: '{local}/products/social'
paths:
/socialProfiles:
get:
summary: List Social Profiles
responses:
'200':
description: OK
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/socialProfiles'
links:
type: object
properties:
self:
type: string
format: uri
first:
type: string
format: uri
description: Provides a link back to the first page of results.
next:
type: string
format: uri
description: The URI at which the next page of results can be gotten from.
operationId: get-socialProfiles
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`
This endpoint returns Social Profile data for the given BusinessLocation. At least one filter is required to call this endpoint unless you have an existing cursor.
parameters:
- schema:
type: string
example: AG-12345
in: query
name: 'filter[businessLocation.id]'
description: Returns all Social Profiles for the given Business Location.
- schema:
type: string
in: query
name: 'page[cursor]'
description: The cursor stores all your filters and current location in the list to allow paging over the results in smaller batches. The value will be provided in the response links. [Pagination Docs](https://developers.vendasta.com/platform/ZG9jOjEwMTkzMDg0-overview#paging).
- schema:
type: integer
example: 20
default: 25
in: query
name: 'page[limit]'
description: The maximum number of Social Profiles you would like to return. [Pagination Docs](https://developers.vendasta.com/platform/ZG9jOjEwMTkzMDg0-overview#paging).
tags:
- Social Profiles
x-lifecycle:
status: trustedTester
options:
summary: List valid HTTP verbs for /socialProfiles
operationId: options-socialProfiles
description: 'Used solely for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) the OPTIONS request returns the list of possible HTTP methods and other headers that browsers use to protect user''s security. You should not call this operation directly. '
responses:
'204':
description: No Content
tags:
- Options
- Social Profiles
x-lifecycle:
status: trustedTester
/messages:
options:
summary: List valid HTTP verbs for /messages
operationId: options-messages
description: 'Used solely for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) the OPTIONS request returns the list of possible HTTP methods and other headers that browsers use to protect user''s security. You should not call this operation directly. '
responses:
'204':
description: No Content
tags:
- Options
- Messages
x-lifecycle:
status: trustedTester
get:
summary: List Social Messages
operationId: get-messages
responses:
'200':
description: OK
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/messages'
links:
type: object
properties:
self:
type: string
format: uri
first:
type: string
format: uri
description: Provides a link back to the first page of results.
next:
type: string
format: uri
description: The URI at which the next page of results can be gotten from.
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`
An endpoint dedicated to listing all the posts made by the business filtered by the selected parameters.
parameters:
- schema:
type: string
example: AG-12345
in: query
name: 'filter[businessLocation.id]'
description: Returns all the posts for a business.
- schema:
type: string
in: query
name: 'page[cursor]'
description: The cursor stores all your filters and current location in the list to allow paging over the results in smaller batches. The value will be provided in the response links.
- schema:
type: integer
example: 20
default: 25
in: query
name: 'page[limit]'
description: The maximum number of Social Posts you would like to return.
- schema:
type: string
example: 'Jd6889Js3,PostGroup1'
in: query
name: 'filter[socialProfileExternalIds]'
description: 'A comma-seperated list filtering messages to profiles with these external identifiers.'
- schema:
type: string
example: '2022-02-04T16:52:34.000Z'
in: query
name: 'filter[startAt]'
description: 'All the messages scheduled to be posted from the timestamp. Times used must be in ISO 8601 format, UTC time.'
- schema:
type: string
example: '2022-02-04T16:52:34.000Z'
in: query
name: 'filter[endAt]'
description: 'All the messaged scheduled to posted at the end of timestamp. Times used must be in ISO 8601 format, UTC time.'
- schema:
type: string
example: 'FBU-839,IGU-762348'
name: 'filter[socialProfileIds]'
in: query
description: Comma seperated string representing all the social profile ids from which the posts are to be listed. The list of profile ids can be obtained from /socialProfiles endpoint.
- schema:
type: string
in: query
name: 'filter[statuses]'
description: 'Comma seperated string containing the statuses of the messages to be listed. The statuses can be scheduled, posted or failed.'
tags:
- Messages
x-lifecycle:
status: trustedTester
post:
summary: Schedule Message
operationId: post-messages
description: Please contact Sales to learn more about the scheduling message API
tags:
- Messages
responses:
'200':
description: OK
components:
securitySchemes:
JWT:
type: http
scheme: bearer
bearerFormat: JWT
OAuth2Demo:
type: oauth2
flows:
authorizationCode:
authorizationUrl: 'https://sso-api-demo.apigateway.co/oauth2/auth'
tokenUrl: 'https://sso-api-demo.apigateway.co/oauth2/token'
scopes:
business: Read-write access to business details
social: Read-write access to Social AI APIs
OAuth2Prod:
type: oauth2
flows:
authorizationCode:
authorizationUrl: 'https://sso-api-prod.apigateway.co/oauth2/auth'
tokenUrl: 'https://sso-api-prod.apigateway.co/oauth2/token'
scopes:
business: Read-write access to business details
social: Read-write access to Social AI APIs
schemas:
socialProfiles:
title: Social Profiles
type: object
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`
An entity that contains the information of a connected account or page with a social network.
x-tags:
- Social Profiles
x-lifecycle:
status: trustedTester
properties:
type:
type: string
default: socialProfiles
id:
type: string
example: FBU-117641035298609261021
description: The unique id for this Social Profile.
attributes:
type: object
properties:
name:
type: string
example: John's Delivery
description: The name of this profile.
avatarUrl:
type: string
description: The link to an url for the avatar image of this profile.
socialNetwork:
type: string
description: A string enum representing which social network this Social Profile is on.
enum:
- facebook
- twitter
- gmb
- linkedinCompany
- linkedinUser
- instagram
status:
type: string
description: 'A string enum that describes the current state of this Social Profile. This may include possibilities like needing user reauthentication, or being disabled due to edition changes.'
enum:
- disabled
- active
- authorizationRequired
statusReason:
type: string
description: 'If status is not ACTIVE, this will be filled with a string describing steps to fix this. Currently only in proposed stage.'
relationships:
type: object
properties:
businessLocation:
type: object
description: The business location that is allowed to post to this socialProfile.
properties:
data:
type: object
properties:
type:
type: string
default: businessLocations
readOnly: true
id:
type: string
example: AG-12AB5
required:
- type
- id
required:
- businessLocation
required:
- type
messages:
title: Messages
type: object
description: |-
[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`
A data structure that describes a message you wish to schedule to be posted on a social network.
examples: [ ]
x-tags:
- Messages
properties:
id:
type: string
description: A unique identifier assigned to this message. We will automatically assign the Message one on creation.
type:
type: string
default: messages
attributes:
type: object
properties:
messageText:
type: string
description: 'The text of the message you’re making. This text is subject to limitations depending on what service you are posting to, such as Tweet length for Twitter. '
status:
type: string
enum:
- scheduled
- posted
- failed
description: |-
The status of the message will be automatically set to one of the following by the system:
scheduled: The message has been approved and is scheduled to be sent at the time indicated in `scheduledAt`
posted: The message was successfully sent to the social profile
failed: An error occurred when sending the message. You can view the details in the `error` attribute.
example: scheduled
readOnly: true
media:
type: array
description: An array containing the media attached to the post.
items:
type: object
properties:
type:
type: string
enum:
- image
- video
- gif
example: image
readOnly: true
url:
type: string
example: 'https://www.example.com/image.jpg'
postedAt:
type: string
format: date-time
description: |-
A string representing the timestamp at which the post was posted.
Times used must be in ISO 8601 format, UTC time.
example: '2022-02-04T16:52:34.000Z'
scheduledAt:
type: string
format: date-time
description: |-
A string representing the timestamp at which the post is scheduled.
Defaults to 5 minutes after the Message is made, and must be at least 5 minutes after the Message is created.
Times used must be in ISO 8601 format, UTC time.
example: '2022-02-04T16:52:34.000Z'
errors:
type: array
description: An array of error objects.
readOnly: true
items:
type: object
properties:
details:
type: string
description: The description of the error.
example: The post is not valid.
GMBPostCustomization:
type: object
description: |-
A special data structure that can be passed in to allow for special attached events for messages posted on Google My Business.
You can add an Event, a Call to Action, or both. If you want an Event, the `title`, `eventStartAt`, and `eventEndAt` fields must all be filled out. If you want a Call To Action, the `CTAType` and `linkUrl` fields must be filled out. `linkUrl` is optional if the CTAType is `callNow`.
properties:
title:
type: string
description: A title for the attached event.
eventStartAt:
type: string
description: The time at which the attached event will start.
eventEndAt:
type: string
description: The time at which the attached event will end.
CTAType:
type: string
enum:
- book
- order
- learnMore
- signup
- shop
- callNow
description: An enum for which Call to Action you wish to use.
linkURL:
type: string
description: A Url for a link you want to associate with your Call to Action.
required:
- messageText
relationships:
type: object
properties:
socialProfiles:
type: object
description: The Social Profiles we’re posting this message under.
properties:
data:
type: array
items:
type: object
properties:
type:
type: string
default: socialProfiles
readOnly: true
id:
type: string
required:
- type
- id
businessLocation:
type: object
description: The location that owns the social profiles that posts will be sent from.
required:
- data
properties:
data:
type: object
required:
- type
- id
properties:
type:
type: string
default: businessLocations
id:
type: string
required:
- socialProfiles
- businessLocation
required:
- type
tags:
- name: Social Profiles
- name: Messages
- name: Options
security:
- OAuth2Demo:
- business
- social
- OAuth2Prod:
- business
- social