> ## Documentation Index
> Fetch the complete documentation index at: https://www.spacebring.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve campaigns
> Retrieve the campaigns of the network, newest first, or only those whose audience includes a location. A campaign belongs to the network and reaches the members of the locations in its audience. With bearer token authentication, the user must be an administrator, and the list leaves out campaigns in none of whose locations they can view campaigns. OAuth
Required scopes: campaigns.readonly or campaigns
## OpenAPI
````yaml /assets/openapi.json get /campaigns/v1
openapi: 3.0.2
info:
title: Spacebring
version: 1.0.0
termsOfService: https://www.spacebring.com/terms
servers:
- url: https://api.spacebring.com
security: []
paths:
/campaigns/v1:
get:
tags:
- Campaigns
summary: Retrieve campaigns
description: >-
Retrieve the campaigns of the network, newest first, or only those whose
audience includes a location. A campaign belongs to the network and
reaches the members of the locations in its audience. With bearer token
authentication, the user must be an administrator, and the list leaves
out campaigns in none of whose locations they can view campaigns.
OAuth
Required scopes: campaigns.readonly or
campaigns
operationId: getCampaigns
parameters:
- in: query
name: channel
required: false
description: 'Filter by channel. Comma-separated, one or more of: email, push.'
schema:
type: string
- in: query
name: id
required: false
description: >-
IDs of the campaigns to get, up to 25. The campaigns found are
returned on one page, newest first. Comma-separated, one or more
UUIDs.
schema:
type: string
- in: query
name: limit
required: false
description: Maximum number of campaigns per page. Defaults to 25.
schema:
type: integer
minimum: 1
maximum: 100
- in: query
name: locationRef
required: false
description: >-
ID of a location whose campaigns to list: those whose audience
includes it. Lists the campaigns of every location when omitted.
schema:
type: string
format: uuid
- in: query
name: nextPageToken
required: false
description: Token of the page to read next.
schema:
type: string
- in: query
name: status
required: false
description: >-
Filter by stage. Comma-separated, one or more of: draft, scheduled,
sending, sent, canceled, failed.
schema:
type: string
- in: header
name: spacebring-network-id
schema:
type: string
format: uuid
required: false
description: >-
The id of the network. Required when using bearer token
authentication
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/getCampaigns'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/responseError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/responseError'
security:
- BasicAuth: []
- OAuth2:
- campaigns.readonly
- campaigns
components:
schemas:
getCampaigns:
type: object
properties:
campaigns:
type: array
items:
type: object
properties:
audience:
type: object
properties:
locationRefs:
type: array
items:
type: string
format: uuid
description: >-
IDs of the locations whose active members the rules choose
from.
rules:
type: array
items:
oneOf:
- type: object
properties:
companyRefs:
type: array
items:
type: string
format: uuid
description: IDs of the companies whose people match.
type:
type: string
enum:
- companies
description: Members of the given companies.
required:
- companyRefs
- type
additionalProperties: false
- type: object
properties:
eventRefs:
type: array
items:
type: string
format: uuid
description: IDs of the events whose attendees match.
type:
type: string
enum:
- eventAttendees
description: Attendees of the given events.
required:
- eventRefs
- type
additionalProperties: false
- type: object
properties:
membershipTypes:
type: array
items:
type: string
enum:
- member
- nonmember
description: Membership types whose customers match.
type:
type: string
enum:
- membershipTypes
description: >-
Everyone at the locations with one of the given
membership types.
required:
- membershipTypes
- type
additionalProperties: false
- type: object
properties:
type:
type: string
enum:
- people
description: The given people.
userRefs:
type: array
items:
type: string
format: uuid
description: IDs of the users who match.
required:
- type
- userRefs
additionalProperties: false
- type: object
properties:
planRefs:
type: array
items:
type: string
format: uuid
description: IDs of the plans whose holders match.
type:
type: string
enum:
- plans
description: >-
People holding an active subscription to one of
the given plans, personally or through their
company.
required:
- planRefs
- type
additionalProperties: false
- type: object
properties:
tierRefs:
type: array
items:
type: string
format: uuid
description: IDs of the resource tiers whose holders match.
type:
type: string
enum:
- resourceTiers
description: >-
People holding an active subscription to one of
the given resource tiers, personally or through
their company.
required:
- tierRefs
- type
additionalProperties: false
description: >-
Rules a member or nonmember of the locations has to match
at least one of. A person who matches several rules gets
one message. With no rules, every active member of the
locations matches, and no nonmember.
required:
- locationRefs
- rules
additionalProperties: false
description: Who receives the campaign.
channel:
type: string
enum:
- email
- push
description: Channel the campaign is sent through.
charge:
description: >-
What sending cost, debited from the network balance when
sending started. Present for sent email campaigns.
type: object
properties:
amount:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: Amount debited, in minor units of the currency.
currencyCode:
type: string
description: ISO 4217 currency code of the amount.
required:
- amount
- currencyCode
additionalProperties: false
createDate:
type: string
format: date-time
description: ISO timestamp of when the campaign was created.
createdBy:
description: >-
Admin who created the campaign. Absent for a campaign created
with client credentials.
type: object
properties:
id:
type: string
format: uuid
description: ID of the admin who created the campaign.
required:
- id
additionalProperties: false
email:
description: Email content, used when the channel is email.
type: object
properties:
body:
type: string
description: Body of the email, in the same markdown as a Feed post.
buttonLabel:
description: Label of the button below the body.
type: string
buttonUrl:
description: Link the button opens.
type: string
replyTo:
description: >-
Address replies go to. Defaults to the network's email
when omitted.
type: string
subject:
type: string
description: Subject of the email.
required:
- body
- subject
additionalProperties: false
id:
type: string
format: uuid
description: Unique identifier of the campaign.
name:
type: string
description: Name of the campaign, shown to admins only.
push:
description: Push content, used when the channel is push.
type: object
properties:
body:
type: string
description: Body of the push notification.
link:
description: >-
Link to the member web portal page the notification opens
in the member app. The member app home when omitted.
type: string
title:
type: string
description: Title of the push notification.
required:
- body
- title
additionalProperties: false
scheduleDate:
description: ISO timestamp of when the campaign is scheduled to be sent.
type: string
format: date-time
sendDate:
description: ISO timestamp of when sending started.
type: string
format: date-time
stats:
type: object
properties:
bounced:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: Number of recipients whose email bounced.
clicked:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Number of recipients who clicked a link in the email at
least once.
complained:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: Number of recipients who marked the email as spam.
delivered:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: Number of recipients whose mail server accepted the email.
opened:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: Number of recipients who opened the email at least once.
recipients:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Number of people the campaign was sent to. Zero until
sending starts.
required:
- bounced
- clicked
- complained
- delivered
- opened
- recipients
additionalProperties: false
description: Delivery statistics of the campaign.
status:
type: string
enum:
- draft
- scheduled
- sending
- sent
- canceled
- failed
description: Stage of the campaign.
updateDate:
type: string
format: date-time
description: ISO timestamp of when the campaign was last changed.
required:
- audience
- channel
- createDate
- id
- name
- stats
- status
- updateDate
additionalProperties: false
description: List of campaigns, newest first.
nextPageToken:
description: Pagination token to fetch the next page of results.
type: string
searchQueryNext:
description: >-
Search query parameters for the next page of results. Includes all
filters used to fetch the current page.
type: string
required:
- campaigns
additionalProperties: false
responseError:
type: object
properties:
message:
type: string
type:
type: string
securitySchemes:
BasicAuth:
type: http
description: >-
See our [authentication
documentation](https://www.spacebring.com/docs/developer/api/authentication#basic-authentication)
for how to authorize your requests
scheme: basic
OAuth2:
type: oauth2
description: >-
See our [authentication
documentation](https://www.spacebring.com/docs/developer/api/authentication#oauth2)
for how to authorize your requests
flows:
authorizationCode:
authorizationUrl: https://oauth2.spacebring.com/api/oauth2/authorize
tokenUrl: https://oauth2.spacebring.com/api/oauth2/token
refreshUrl: https://oauth2.spacebring.com/api/oauth2/token
scopes:
benefits.readonly: Read benefits and applications
benefits: Read and write benefits and applications
campaigns.readonly: Read campaigns
campaigns: Read and write campaigns
checkIns.readonly: Read check-ins
checkIns: Read and write check-ins
community.readonly: Read community companies and memberships
community: Read and write community companies and memberships
events.readonly: Read events and tickets
events: Read and write events and tickets
feed.readonly: Read feed posts
feed: Read and write feed posts
invoices.readonly: Read contracts, credit notes, discounts and invoices
invoices: Read and write contract, credit notes, discounts and invoices
locations.readonly: Read locations
locations: Read and write locations
plans.readonly: Read plans
plans: Read and write plans
resources.readonly: Read resources and bookings
resources: Read and write resources and bookings
subscriptions.readonly: Read subscriptions
subscriptions: Read and write subscriptions
shop.readonly: Read products and orders
shop: Read and write products and orders
support.readonly: Read support tickets
support: Read and write support tickets
transactions.readonly: Read transactions
transactions: Read and write transactions
visitors.readonly: Read visitors
visitors: Read and write visitors
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.