{ "openapi": "3.0.1", "info": { "title": "Roster API", "description": "The Roster API allows you to build integrations that extend and enhance the Roster experience.\n The information below will guide you as you build your applications and integrations. \n You can also use our api explorer in preparation for development.\n If you need assistance or have any questions, please contact support@getroster.com", "version": "v2", "x-logo": { "url": "https://app.getroster.com/img/logo-text-white.png", "altText": "Roster API Logo" } }, "servers": [ { "url": "https://api.getroster.com" } ], "paths": { "/v2/attributions/{attributionId}": { "get": { "tags": [ "Attribution" ], "summary": "Retrieves a single attribution", "parameters": [ { "name": "attributionId", "in": "path", "description": "The Attribution ID", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "referralId", "in": "query", "description": "Attributions resulting from this referral ID (the identifier in the ambassador’s referral link)", "schema": { "type": "string", "example": "somecustomid" }, "example": "somecustomid" }, { "name": "smartLinkSource", "in": "query", "description": "Attributions resulting from this smart link source. A smart link's source can be found in the redirect URL when clicking on the smart link. Requires the referralLink parameter to also be passed in.", "schema": { "type": "string", "example": "abc" }, "example": "abc" }, { "name": "smartLinkVariant", "in": "query", "description": "Attributions resulting from this smart link variant. A smart link's variant can be found in the redirect URL when clicking on the smart link variant. Requires the referralLink and smartLinkSource parameters to also be passed in.", "schema": { "type": "string", "example": "abc" }, "example": "abc" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiAttributionOpenApiResult" } } } } } } }, "/v2/attributions": { "get": { "tags": [ "Attribution" ], "summary": "Retrieves a list of all attributions", "parameters": [ { "name": "ambassadorIds", "in": "query", "description": "The list of ambassadors to whom the attribution is credited", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" }, "example": [ 12345, 67890 ] }, "example": [ 12345, 67890 ] }, { "name": "programIds", "in": "query", "description": "The list of programs the ambassadors are associated to", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" }, "example": [ 12345, 67890 ] }, "example": [ 12345, 67890 ] }, { "name": "tagIds", "in": "query", "description": "The list of tag the ambassadors are associated to", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" }, "example": [ 12345, 67890 ] }, "example": [ 12345, 67890 ] }, { "name": "orderId", "in": "query", "description": "Attributions associated with this order ID", "schema": { "type": "integer", "format": "int64", "example": 123456 }, "example": 123456 }, { "name": "externalOrderNumber", "in": "query", "description": "Attributions associated with this external order number (e.g.the Shopify order number)", "schema": { "type": "string", "example": "4561278" }, "example": "4561278" }, { "name": "attributionType", "in": "query", "description": "Attributions of this type. Valid values are: personal, referral", "schema": { "$ref": "#/components/schemas/OpenApiAttributionType" }, "example": "personal" }, { "name": "attributionMethods", "in": "query", "description": "Attributions of this method. Valid values are: Options include: emailAddress, rewardCode, referralLink, discountCode, recurringOrder", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiAttributionMethod" } } }, { "name": "referralId", "in": "query", "description": "Attributions resulting from this referral ID (the identifier in the ambassador's referral link)", "schema": { "type": "string", "example": "somecustomid" }, "example": "somecustomid" }, { "name": "smartLinkSource", "in": "query", "description": "Attributions resulting from this smart link source. A smart link's source can be found in the redirect URL when clicking on the smart link. Requires the referralLink parameter to also be passed in.", "schema": { "type": "string", "example": "abc" }, "example": "abc" }, { "name": "smartLinkVariant", "in": "query", "description": "Attributions resulting from this smart link variant. A smart link's variant can be found in the redirect URL when clicking on the smart link variant. Requires the referralLink and smartLinkSource parameters to also be passed in.", "schema": { "type": "string", "example": "abc" }, "example": "abc" }, { "name": "discountCode", "in": "query", "description": "Attributions resulting from this discount code", "schema": { "type": "string", "example": "DISCOUNT25" }, "example": "DISCOUNT25" }, { "name": "createdAtMin", "in": "query", "description": "Attributions' orders created at or after timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-01T11:59:00" }, "example": "2022-10-01T11:59:00" }, { "name": "createdAtMax", "in": "query", "description": "Attributions' orders created at or before timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-31T11:59:00" }, "example": "2022-10-31T11:59:00" }, { "name": "updatedAtMin", "in": "query", "description": "Attributions updated at or after timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-01T11:59:00" }, "example": "2022-10-01T11:59:00" }, { "name": "updatedAtMax", "in": "query", "description": "Attributions updated at or before timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-31T11:59:00" }, "example": "2022-10-31T11:59:00" }, { "name": "isActive", "in": "query", "description": "Used to return only active attributions", "schema": { "type": "boolean" } }, { "name": "isPaidTraffic", "in": "query", "description": "Filter attributions by the traffic source of the matched click. true = paid ad traffic only, false = organic traffic only.", "schema": { "type": "boolean", "example": true }, "example": true }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "type": "string" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiAttributionResponsePaginatedResult" } } } } } } }, "/v2/campaigns": { "get": { "tags": [ "Campaign" ], "summary": "Retrieves the list of campaigns.", "parameters": [ { "name": "query", "in": "query", "description": "Searches for campaigns whose name or title match the search term", "schema": { "type": "string", "example": "Winter" }, "example": "Winter" }, { "name": "type", "in": "query", "description": "Filters the list by this type", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignType" } } }, { "name": "status", "in": "query", "description": "Filter by campaigns with this status", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignStatus" } } }, { "name": "createdBy", "in": "query", "description": "Filter campaigns by user", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "actionRequired", "in": "query", "description": "Filter by campaigns that require action", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignActionRequired" } } }, { "name": "includeCampaignStats", "in": "query", "description": "Include campaign stats in the response", "schema": { "type": "boolean" } }, { "name": "campaignIds", "in": "query", "description": "Filter to specific campaign ids", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/CampaignSorter" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiCampaignPaginatedResult" } } } } } } }, "/v2/campaigns/{campaignId}/participants": { "get": { "tags": [ "CampaignParticipants" ], "summary": "Retrieves a list of campaign participants", "parameters": [ { "name": "campaignId", "in": "path", "description": "Campaign ID", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "ambassador", "in": "query", "description": "Get specific participants", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" }, "example": [ 12345, 54321 ] }, "example": [ 12345, 54321 ] }, { "name": "status", "in": "query", "description": "Filters the list by this status", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignParticipantsStatus" }, "example": [ "joined", "completed" ] }, "example": [ "joined", "completed" ] }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/CampaignParticipantsSorter" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiCampaignParticipantPaginatedResult" } } } } } } }, "/v2/campaigns/{campaign_id}/performance": { "get": { "tags": [ "CampaignPerformance" ], "summary": "Retrieves one campaign's performance, matching the portal's campaign\r\noverview: the invite/participation funnel, posts and reach, engagement,\r\nearned media value, and reward fulfillment counts. Note: Roster does not\r\nattribute order revenue to campaigns — for revenue use the Sales\r\nAttribution report.", "parameters": [ { "name": "campaign_id", "in": "path", "description": "The Campaign ID", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiCampaignPerformanceResponseOpenApiResult" } } } } } } }, "/v2/campaign/{campaign_id}/rewards": { "get": { "tags": [ "CampaignRewards" ], "summary": "Retrieves a list of all campaign rewards", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "ambassador", "in": "query", "description": "Matches rewards owned by the ambassador", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "type", "in": "query", "description": "Filters the list by this type", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RewardType" } } }, { "name": "status", "in": "query", "description": "Filters the list by this status", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RewardFulfillmentStatus" } } }, { "name": "campaignRewardIssuance", "in": "query", "description": "Filters the list by this campaign reward issuance", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignRewardIssuance" } } }, { "name": "rewardIds", "in": "query", "description": "Matches rewards by their ids", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "createdAtMin", "in": "query", "description": "Rewards created on or after timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-01T11:59:00" }, "example": "2022-10-01T11:59:00" }, { "name": "createdAtMax", "in": "query", "description": "Rewards created on or before timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-31T11:59:00" }, "example": "2022-10-31T11:59:00" }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/RewardSorter" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiCampaignRewardPaginatedResult" } } } } } } }, "/v2/cash-rewards": { "get": { "tags": [ "CashRewards" ], "summary": "Retrieves a list of cash rewards. Points rewards can never appear in this list.", "parameters": [ { "name": "ambassadorId", "in": "query", "description": "Matches cash rewards owned by these ambassadors. Repeatable - the Brand Portal's\r\nambassador filter is multi-select.", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "rewardStatus", "in": "query", "description": "Filters the list by status", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CashRewardStatus" } } }, { "name": "source", "in": "query", "description": "Filters the list by where the cash came from", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CashRewardSource" } } }, { "name": "earnedAtMin", "in": "query", "description": "Cash earned on or after this timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2026-08-01T11:59:00" }, "example": "2026-08-01T11:59:00" }, { "name": "earnedAtMax", "in": "query", "description": "Cash earned on or before this timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2026-08-31T11:59:00" }, "example": "2026-08-31T11:59:00" }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/CashRewardSorter" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCashRewardPaginatedResultOpenApiResult" } } } } } }, "post": { "tags": [ "CashRewards" ], "summary": "Creates a manual cash reward - money owed for work with no campaign or milestone behind it.\r\nRequires a configured payment gateway, like every other cash reward.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiManualCashRewardPostRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiManualCashRewardPostRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiManualCashRewardPostRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCashRewardOpenApiResult" } } } } } } }, "/v2/cash-rewards/summary": { "get": { "tags": [ "CashRewards" ], "summary": "Retrieves the cash-only summary totals for the ledger. Never combined with points.", "parameters": [ { "name": "ambassadorId", "in": "query", "description": "Matches cash rewards owned by these ambassadors. Repeatable - the Brand Portal's\r\nambassador filter is multi-select.", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "rewardStatus", "in": "query", "description": "Filters the list by status", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CashRewardStatus" } } }, { "name": "source", "in": "query", "description": "Filters the list by where the cash came from", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CashRewardSource" } } }, { "name": "earnedAtMin", "in": "query", "description": "Cash earned on or after this timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2026-08-01T11:59:00" }, "example": "2026-08-01T11:59:00" }, { "name": "earnedAtMax", "in": "query", "description": "Cash earned on or before this timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2026-08-31T11:59:00" }, "example": "2026-08-31T11:59:00" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCashRewardSummaryOpenApiResult" } } } } } } }, "/v2/cash-rewards/approve": { "post": { "tags": [ "CashRewards" ], "summary": "Approves pending cash rewards. Approving does not pay them - payment happens in a batch.", "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "text/json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "application/*+json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } }, "/v2/cash-rewards/reject": { "post": { "tags": [ "CashRewards" ], "summary": "Rejects pending cash rewards.", "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "text/json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "application/*+json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } }, "/v2/cash-rewards/undo": { "post": { "tags": [ "CashRewards" ], "summary": "Sets approved or rejected cash rewards back to pending.", "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "text/json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "application/*+json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } }, "/v2/community/channels/{channel_id}/participants": { "get": { "tags": [ "ChannelParticipants" ], "summary": "Retrieves a list of a channel’s participants", "parameters": [ { "name": "channel_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "contactIds", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "programIds", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/ParticipantSorter" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiChannelPaginatedResultOpenApiResult" } } } } } }, "delete": { "tags": [ "ChannelParticipants" ], "summary": "Removes participants from a channel", "parameters": [ { "name": "channel_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "contactIds", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } }, "/v2/community/channels/{channel_id}/programs": { "put": { "tags": [ "ChannelPrograms" ], "parameters": [ { "name": "channel_id", "in": "path", "description": "The id of the channel to update", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCommunityChannelProgramsPutRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UserCommunityChannelProgramsPutRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UserCommunityChannelProgramsPutRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } }, "/v2/community/channels": { "get": { "tags": [ "Channels" ], "summary": "Retrieves a list of channels", "parameters": [ { "name": "program", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } }, { "name": "status", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelStatus" } } }, { "name": "searchText", "in": "query", "schema": { "type": "string" } }, { "name": "createdAtMin", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "createdAtMax", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/ChannelSorter" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiChannelPaginatedResultOpenApiResult" } } } } } }, "post": { "tags": [ "Channels" ], "summary": "Creates a channel", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiChannelPostRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiChannelPostRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiChannelPostRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiChannelOpenApiResult" } } } } } } }, "/v2/community/channels/{channel_id}": { "get": { "tags": [ "Channels" ], "summary": "Retrieves a specific channel", "parameters": [ { "name": "channel_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiChannelOpenApiResult" } } } } } }, "put": { "tags": [ "Channels" ], "summary": "Updates a channel", "parameters": [ { "name": "channel_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiChannelPostRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiChannelPostRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiChannelPostRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiChannelOpenApiResult" } } } } } } }, "/v2/clicks": { "get": { "tags": [ "Clicks" ], "summary": "Retrieves a list of all clicks", "parameters": [ { "name": "ambassadorId", "in": "query", "description": "The ambassador who owns the referral link that was clicked", "schema": { "type": "integer", "format": "int64", "example": 1234123 }, "example": 1234123 }, { "name": "referralLinkId", "in": "query", "description": "The referral identifier from the referral link (e.g. in the referral link `https://example.com/?rstr=123abc`, the referral ID is `123abc`", "schema": { "type": "string", "example": "123abc" }, "example": "123abc" }, { "name": "createdAtMin", "in": "query", "description": "Clicks created at or after timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-01T11:59:00" }, "example": "2022-10-01T11:59:00" }, { "name": "createdAtMax", "in": "query", "description": "Clicks created at or before timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-01T11:59:00" }, "example": "2022-10-01T11:59:00" }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiClickListOpenApiResult" } } } } } }, "post": { "tags": [ "Clicks" ], "summary": "Creates a link click", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiCreateClickParams" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiCreateClickParams" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiCreateClickParams" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } }, "/v2/clicks/capture": { "post": { "tags": [ "Clicks" ], "summary": "Creates a click using a public access token", "description": "Captures referral link clicks from website visitors using a public access token and a `ReferralLinkId` associated with an ambassador.\r\nOptionally, include query params to further enrich the referral tracking data to know how the click came into the system.\r\n \r\nTo generate an access token, go to your brand settings page to create a new \"Public Access Token\".\r\nThen you'll need to add the necessary code for site wide referral link tracking.\r\nVisit our knowledge-base for more information.", "parameters": [ { "name": "access_token", "in": "query", "description": "The public access token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiCaptureClickParams" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiCaptureClickParams" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiCaptureClickParams" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } }, "/v2/community/comments": { "get": { "tags": [ "Comments" ], "summary": "Retrieves a list of comments", "parameters": [ { "name": "parentId", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "parentType", "in": "query", "schema": { "$ref": "#/components/schemas/ParentType" } }, { "name": "userId", "in": "query", "schema": { "type": "integer", "format": "int64" } }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "type": "string" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiCommentPaginatedResultOpenApiResult" } } } } } }, "post": { "tags": [ "Comments" ], "summary": "Creates a comment for a post or comment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentPostRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CommentPostRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CommentPostRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiCommentOpenApiResult" } } } } } } }, "/v2/community/comments/{comment_id}": { "get": { "tags": [ "Comments" ], "summary": "Retrieves a specific comment", "parameters": [ { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiCommentOpenApiResult" } } } } } } }, "/v2/community/profiles/me": { "get": { "tags": [ "CommunityProfile" ], "summary": "Retrieves a profile", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiCommunityProfileOpenApiResult" } } } } } }, "put": { "tags": [ "CommunityProfile" ], "summary": "Updates a profile", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiProfileUpsertRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiProfileUpsertRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiProfileUpsertRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } }, "/v2/contacts/{contact_id}/performance": { "get": { "tags": [ "ContactPerformance" ], "summary": "Retrieves one contact's performance, mirroring the portal's contact\r\ndetail page: lifetime referral revenue and orders, personal orders,\r\ncommission totals by status, and social posts with engagement and EMV.\r\nCombine with GET /v2/contacts/{contact_id} for the profile.", "parameters": [ { "name": "contact_id", "in": "path", "description": "The contact (account) ID", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiContactPerformanceResponseOpenApiResult" } } } } } } }, "/v2/contacts/{contact_id}/properties": { "get": { "tags": [ "ContactProperties" ], "summary": "Retrieves a list of a contact’s properties", "parameters": [ { "name": "contact_id", "in": "path", "description": "The contact to retrieve", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiContactPropertyOpenApiResult" } } } } } }, "post": { "tags": [ "ContactProperties" ], "summary": "Sets a property for a contact", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiContactPropertyPostRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiContactPropertyPostRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiContactPropertyPostRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiContactPropertyOpenApiResult" } } } } } } }, "/v2/contacts/{contact_id}/properties/{property_id}": { "get": { "tags": [ "ContactProperties" ], "summary": "Retrieves a specific property for a contact", "parameters": [ { "name": "contact_id", "in": "path", "description": "The id of the contact to retrieve", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "property_id", "in": "path", "description": "The id of the property to retrieve", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiContact" } } } } } } }, "put": { "tags": [ "ContactProperties" ], "summary": "Updates a property for a contact", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "property_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiContactPropertyPutRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiContactPropertyPutRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiContactPropertyPutRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiContactPropertyOpenApiResult" } } } } } }, "delete": { "tags": [ "ContactProperties" ], "summary": "Deletes a property from a contact", "parameters": [ { "name": "contact_id", "in": "path", "description": "The id of the contact to delete", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "property_id", "in": "path", "description": "The id of the property to delete", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } }, "/v2/contacts/{contact_id}": { "get": { "tags": [ "Contacts" ], "summary": "Retrieves a single contact", "parameters": [ { "name": "contact_id", "in": "path", "description": "The contact to retrieve", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "includeMagicLinkCode", "in": "query", "description": "If true and if magic links are enabled for the brand, Includes contact’s magic code", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiContactOpenApiResult" } } } } } }, "delete": { "tags": [ "Contacts" ], "summary": "Deletes a single contact", "parameters": [ { "name": "contact_id", "in": "path", "description": "The contact to delete", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } }, "/v2/contacts": { "get": { "tags": [ "Contacts" ], "summary": "Retrieves a list of all contacts", "parameters": [ { "name": "contactIds", "in": "query", "description": "The list of contact's system generated unique ID to filter by", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" }, "example": [ 12345, 67890 ] }, "example": [ 12345, 67890 ] }, { "name": "email", "in": "query", "description": "Contact's email address to filter by", "schema": { "type": "string", "example": "example@email.com" }, "example": "example@email.com" }, { "name": "instagramHandle", "in": "query", "description": "Contact's instagram handle to filter by", "schema": { "type": "string", "example": "instagram_handle" }, "example": "instagram_handle" }, { "name": "referralLinkId", "in": "query", "description": "Contact's referral link id to filter by", "schema": { "type": "string", "example": "54321" }, "example": "54321" }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiContact" } } } } } } }, "post": { "tags": [ "Contacts" ], "summary": "Create a single contact", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiContactPostRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiContactPostRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiContactPostRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiContactOpenApiResult" } } } } } }, "put": { "tags": [ "Contacts" ], "summary": "Updates a single contact", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiContactPutRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiContactPutRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiContactPutRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiContactOpenApiResult" } } } } } } }, "/v2/contacts/search": { "get": { "tags": [ "ContactSearch" ], "summary": "Searches the brand's contacts — the same search the portal's contact\r\nlist uses — with performance fields (lifetime referral revenue and\r\norders, post mentions, followers, engagement) for building\r\nleaderboards and exports.", "parameters": [ { "name": "query", "in": "query", "description": "Free-text search over names, emails, and handles", "schema": { "type": "string" } }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/OpenApiContactSearchSortField" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiContactSearchRowPaginatedResult" } } } } } } }, "/v2/discount-codes/lookup": { "get": { "tags": [ "DiscountCodes" ], "summary": "Retrieves the location of a specific discount code", "parameters": [ { "name": "code", "in": "query", "description": "The code to be looked up", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDiscountCode" } } } } } } }, "/v2/discount-codes/{discountCodeId}": { "get": { "tags": [ "DiscountCodes" ], "summary": "Retrieves a specific discount code", "parameters": [ { "name": "discountCodeId", "in": "path", "description": "The Discount Code", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDiscountCode" } } } } } } }, "/v2/discount-codes/{discountCodeId}/deactivate": { "post": { "tags": [ "DiscountCodes" ], "summary": "Deactivate an ambassador’s discount code", "parameters": [ { "name": "discountCodeId", "in": "path", "description": "The Discount Code", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDiscountCode" } } } } } } }, "/v2/discount-rules/{discountRuleId}/discount-codes": { "get": { "tags": [ "DiscountCodes" ], "summary": "Retrieves a list of discount codes for a discount rule", "parameters": [ { "name": "discountRuleId", "in": "path", "description": "The Discount Rule", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "query", "in": "query", "description": "Searches for discount codes that match the search term", "schema": { "type": "string", "example": "Roster" }, "example": "Roster" }, { "name": "ambassador", "in": "query", "description": "Matches discount codes owned by the ambassador", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" }, "example": [ 12345, 54321 ] }, "example": [ 12345, 54321 ] }, { "name": "status", "in": "query", "description": "Filters the list by this status", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DiscounCodeStatus" } } }, { "name": "codeIds", "in": "query", "description": "Filters the list by this set of discount codes", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" }, "example": [ 12345, 54321 ] }, "example": [ 12345, 54321 ] }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/DiscountCodeSorter" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDiscountCodePaginatedResult" } } } } } }, "post": { "tags": [ "DiscountCodes" ], "summary": "Create and assign a discount code to an ambassador", "parameters": [ { "name": "discountRuleId", "in": "path", "description": "The Discount Rule", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCodeRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateCodeRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateCodeRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDiscountCode" } } } } } } }, "/v2/discount-rules": { "get": { "tags": [ "DiscountRules" ], "summary": "Retrieves a list of all discount rules", "parameters": [ { "name": "query", "in": "query", "description": "Searches for discount codes that match the search term", "schema": { "type": "string", "example": "Roster" }, "example": "Roster" }, { "name": "ambassador", "in": "query", "description": "Matches discount codes owned by the ambassador", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" }, "example": [ 12345, 54321 ] }, "example": [ 12345, 54321 ] }, { "name": "ruleType", "in": "query", "description": "Filters the list by this type", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RuleTypes" } } }, { "name": "status", "in": "query", "description": "Filters the list by this status", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RuleStatus" } } }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/DiscountRuleSorter" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDiscountRulePaginatedResult" } } } } } } }, "/v2/discount-rules/{discountRuleId}": { "get": { "tags": [ "DiscountRules" ], "summary": "Retrieves a specific discount rule", "parameters": [ { "name": "discountRuleId", "in": "path", "description": "The Discount Rule", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDiscountRule" } } } } } }, "delete": { "tags": [ "DiscountRules" ], "summary": "Delete a discount rule that doesn’t have any assigned codes or isn’t linked to another object", "parameters": [ { "name": "discountRuleId", "in": "path", "description": "The Discount Rule", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK" } } } }, "/v2/discount-rules/{discountRuleId}/import/assigned": { "post": { "tags": [ "DiscountRules" ], "summary": "Import a batch of assigned discount codes into a discount rule", "parameters": [ { "name": "discountRuleId", "in": "path", "description": "The Discount Rule", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignedCodeImportRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/AssignedCodeImportRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/AssignedCodeImportRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/v2/discount-rules/{discountRuleId}/import/unassigned": { "post": { "tags": [ "DiscountRules" ], "summary": "Import a batch of unassigned discount codes into a discount rule", "parameters": [ { "name": "discountRuleId", "in": "path", "description": "The Discount Rule", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnassignedCodeImportRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UnassignedCodeImportRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UnassignedCodeImportRequest" } } } }, "responses": { "200": { "description": "OK" } } } }, "/v2/discount-rules/{discountRuleId}/unassigned": { "delete": { "tags": [ "DiscountRules" ], "summary": "Delete unassigned discount codes in a discount rule", "parameters": [ { "name": "discountRuleId", "in": "path", "description": "The Discount Rule", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK" } } } }, "/v2/discount-rules/{discountRuleId}/archive": { "post": { "tags": [ "DiscountRules" ], "summary": "Archive an expired discount rule. Deactivates all codes and queues Shopify cleanup if applicable.", "parameters": [ { "name": "discountRuleId", "in": "path", "description": "The Discount Rule to archive", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK" } } } }, "/v2/events": { "get": { "tags": [ "Events" ], "summary": "Retrieves a list of all events", "parameters": [ { "name": "subjectType", "in": "query", "description": "Filter by event's subject type.", "schema": { "$ref": "#/components/schemas/EventSubjectType" }, "example": "reward" }, { "name": "verb", "in": "query", "description": "Filter by event's verb.", "schema": { "$ref": "#/components/schemas/EventVerbType" }, "example": "redeemed" }, { "name": "subjectId", "in": "query", "description": "Filter by event's subject ID.", "schema": { "type": "integer", "format": "int64", "example": 12345 }, "example": 12345 }, { "name": "sinceId", "in": "query", "description": "Show only events after the specified event ID.", "schema": { "type": "integer", "format": "int64", "example": 12345 }, "example": 12345 }, { "name": "createdAtMin", "in": "query", "description": "Events created at or after timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-01T11:59:00" }, "example": "2022-10-01T11:59:00" }, { "name": "createdAtMax", "in": "query", "description": "Events created at or before timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-01T11:59:00" }, "example": "2022-10-01T11:59:00" }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/EventSorter" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiEventPaginatedResult" } } } } } } }, "/v2/events/{event_id}": { "get": { "tags": [ "Events" ], "summary": "Retrieves a specific event", "parameters": [ { "name": "event_id", "in": "path", "description": "The event ID", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiEventOpenApiResult" } } } } } } }, "/v2/contacts/import": { "post": { "tags": [ "Import" ], "summary": "Creates a new contact import job", "description": "Accepts JSON payload with CSV data converted to rows and import options.\r\nOnly one import can be active per brand at a time.\r\nImports with 1,000+ rows are routed to manual review.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactImportRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ContactImportRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ContactImportRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactImportResponseOpenApiResult" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } }, "/v2/contacts/import/sample-csv": { "get": { "tags": [ "Import" ], "summary": "Downloads a sample CSV template for contact imports", "description": "Returns a CSV file with all supported column headers, including the brand's custom property slugs.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/v2/contacts/import/status": { "get": { "tags": [ "Import" ], "summary": "Checks if the brand has an active contact import job", "description": "Returns true if there's an import task in progress (New, Ready, or Running status).", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportStatusResponseOpenApiResult" } } } } } } }, "/v2/community/likes": { "get": { "tags": [ "Likes" ], "summary": "Retrieves a list of likes", "parameters": [ { "name": "parentId", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "parentType", "in": "query", "schema": { "$ref": "#/components/schemas/ParentType" } }, { "name": "userId", "in": "query", "schema": { "type": "integer", "format": "int64" } }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "type": "string" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiLikePaginatedResultOpenApiResult" } } } } } }, "post": { "tags": [ "Likes" ], "summary": "Creates a like for a post or comment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LikePostRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/LikePostRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/LikePostRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiLikeOpenApiResult" } } } } } } }, "/v2/community/likes/{like_id}": { "delete": { "tags": [ "Likes" ], "summary": "Deletes a like from a post or comment", "parameters": [ { "name": "like_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } }, "/v2/me": { "get": { "tags": [ "Me" ], "summary": "Returns the brand this API token is scoped to (name and portal domain),\r\nwhen the token was created, and its access type. Useful as a lightweight\r\n\"who am I / is this token alive\" check.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiMeResponseOpenApiResult" } } } } } } }, "/v2/milestone-series/{milestoneSeriesId}/participants": { "get": { "tags": [ "MilestoneSeriesParticipants" ], "summary": "Retrieves a list of milestone series participants.", "parameters": [ { "name": "milestoneSeriesId", "in": "path", "description": "Milestone Series ID", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "ambassadorIds", "in": "query", "description": "Filter by these ambassadors (contact IDs)", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" }, "example": [ 12345, 54321 ] }, "example": [ 12345, 54321 ] }, { "name": "programIds", "in": "query", "description": "Filter by participants in these programs", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" }, "example": [ 4145, 7451 ] }, "example": [ 4145, 7451 ] }, { "name": "currentMilestoneIds", "in": "query", "description": "Filter by participants who last unlocked these milestones", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" }, "example": [ 23, 48 ] }, "example": [ 23, 48 ] }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/MilestoneSeriesParticipantsSorter" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiMilestoneSeriesParticipantPaginatedResult" } } } } } } }, "/v2/milestone-series/{milestone_series_id}/rewards": { "get": { "tags": [ "MilestoneSeriesRewards" ], "summary": "Retrieves a list of milestone rewards", "parameters": [ { "name": "milestone_series_id", "in": "path", "description": "Milestone Series ID", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "ambassador", "in": "query", "description": "Matches rewards owned by the ambassador", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "milestone", "in": "query", "description": "Matches rewards from specific milestone", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "program", "in": "query", "description": "Matches rewards owned by the ambassador in Program", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } }, { "name": "status", "in": "query", "description": "Filters the list by this status", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RewardFulfillmentStatus" } } }, { "name": "type", "in": "query", "description": "Filters the list by reward type", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RewardType" } } }, { "name": "rewardIds", "in": "query", "description": "Matches rewards by their ids", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "createdAtMin", "in": "query", "description": "Rewards created on or after timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-01T11:59:00" }, "example": "2022-10-01T11:59:00" }, { "name": "createdAtMax", "in": "query", "description": "Rewards created on or before timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-31T11:59:00" }, "example": "2022-10-31T11:59:00" }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/MilestoneRewardSorter" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiMilestoneSeriesRewardPaginatedResult" } } } } } } }, "/v2/orders": { "get": { "tags": [ "Orders" ], "summary": "Retrieves a list of all orders", "parameters": [ { "name": "customerId", "in": "query", "description": "Filter by orders made by this customer. (the Roster customer ID)", "schema": { "type": "integer", "format": "int64", "example": 123456 }, "example": 123456 }, { "name": "customerEmail", "in": "query", "description": "Filter by orders matching the customer’s email address", "schema": { "type": "string", "example": "example@email.com" }, "example": "example@email.com" }, { "name": "externalOrderNumber", "in": "query", "description": "Filter by orders matching this external order number (e.g. The Shopify order number)", "schema": { "type": "string", "example": "5461272" }, "example": "5461272" }, { "name": "referralLinkId", "in": "query", "description": "Filter by orders made with this referral ID (the identifier in the ambassador’s referral link)", "schema": { "type": "string", "example": "somecustomid" }, "example": "somecustomid" }, { "name": "discountCode", "in": "query", "description": "Filter by orders made from this discount code", "schema": { "type": "string", "example": "DISCOUNT25" }, "example": "DISCOUNT25" }, { "name": "createdAtMin", "in": "query", "description": "Orders created at or after timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-01T11:59:00" }, "example": "2022-10-01T11:59:00" }, { "name": "createdAtMax", "in": "query", "description": "Orders created at or before timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-31T11:59:00" }, "example": "2022-10-31T11:59:00" }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/OrderSorter" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiOrdersGetResponsePaginatedResult" } } } } } }, "post": { "tags": [ "Orders" ], "summary": "Creates an order", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiOrdersPostRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiOrdersPostRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiOrdersPostRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiOrdersGetResponseOpenApiResult" } } } } } } }, "/v2/orders/{order_id}": { "get": { "tags": [ "Orders" ], "summary": "Retrieves a single order", "parameters": [ { "name": "order_id", "in": "path", "description": "The Roster order ID", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiOrdersGetResponseOpenApiResult" } } } } } }, "put": { "tags": [ "Orders" ], "summary": "Updates an order", "parameters": [ { "name": "order_id", "in": "path", "description": "The order ID", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiOrdersPutRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiOrdersPutRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiOrdersPutRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiOrderOpenApiResult" } } } } } } }, "/v2/orders/capture": { "post": { "tags": [ "Orders" ], "summary": "Creates an order using a public access token", "description": "Captures orders from website visitors using a public access token. To capture a referral, send either a `ReferralLinkId` and/or `DiscountCodes` associated with the referring ambassador.\r\nOptionally, include the new customer's name & email to further enrich the order data to know who ambassadors are referring.\r\n \r\nTo generate an access token, go to your brand settings page to create a new \"Public Access Token\".\r\nThen you'll need to add the necessary code for site wide referral link tracking (see the clicks/capture endpoint) and an additional script on your order confirmation page to track completed orders using this endpoint. \r\nVisit our knowledge-base for more information.", "parameters": [ { "name": "access_token", "in": "query", "description": "The public access token", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiOrdersCaptureRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiOrdersCaptureRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiOrdersCaptureRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } }, "/v2/community/posts": { "get": { "tags": [ "Posts" ], "summary": "Retrieves a list of posts", "parameters": [ { "name": "channelIds", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } }, { "name": "status", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Status" } } }, { "name": "userIds", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "searchText", "in": "query", "schema": { "type": "string" } }, { "name": "pinnedFilter", "in": "query", "schema": { "$ref": "#/components/schemas/PinnedFilter" } }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/CommunityPostsSorting" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiPostPaginatedResultOpenApiResult" } } } } } }, "post": { "tags": [ "Posts" ], "summary": "Creates a post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiPostCreateRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiPostCreateRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiPostCreateRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiPostOpenApiResult" } } } } } } }, "/v2/community/posts/{post_id}": { "get": { "tags": [ "Posts" ], "summary": "Retrieves a specific post", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "commentSortDirection", "in": "query", "description": "The direction the comments are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiPostOpenApiResult" } } } } } }, "delete": { "tags": [ "Posts" ], "summary": "Deletes a post and all child records", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } }, "put": { "tags": [ "Posts" ], "summary": "Updates a post", "parameters": [ { "name": "post_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiPostUpdateRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiPostUpdateRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiPostUpdateRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiPostOpenApiResult" } } } } } } }, "/v2/programs/{program_id}/ambassadors": { "get": { "tags": [ "ProgramAmbassadors" ], "summary": "Retrieves the program’s ambassadors", "parameters": [ { "name": "program_id", "in": "path", "description": "The program from which to retrieve the ambassadors", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "contactIds", "in": "query", "description": "Filter the list by these ambassadors (contact IDs.)", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" }, "example": [ 238, 3983, 9382 ] }, "example": [ 238, 3983, 9382 ] }, { "name": "createdAtMin", "in": "query", "description": "Ambassadors added on or after timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-01T11:59:00" }, "example": "2022-10-01T11:59:00" }, { "name": "createdAtMax", "in": "query", "description": "Ambassadors added on or before timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-31T11:59:00" }, "example": "2022-10-31T11:59:00" }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiProgramAmbassadorPaginatedResult" } } } } } }, "post": { "tags": [ "ProgramAmbassadors" ], "summary": "Add a contact to a program as an ambassador", "parameters": [ { "name": "program_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiProgramAmbassadorPostRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiProgramAmbassadorPostRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiProgramAmbassadorPostRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } }, "delete": { "tags": [ "ProgramAmbassadors" ], "summary": "Remove an ambassador from a program", "parameters": [ { "name": "program_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiProgramAmbassadorDeleteRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiProgramAmbassadorDeleteRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiProgramAmbassadorDeleteRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } }, "/v2/programs/{program_id}/applicants": { "get": { "tags": [ "ProgramApplicants" ], "summary": "Retrieves the program's applicants", "parameters": [ { "name": "program_id", "in": "path", "description": "The program from which to retrieve the applicants", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "applicantIds", "in": "query", "description": "Filter by these applicants (contact IDs)", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" }, "example": [ 1254, 657418, 6542345 ] }, "example": [ 1254, 657418, 6542345 ] }, { "name": "status", "in": "query", "description": "Filter by the applicant's current status", "schema": { "$ref": "#/components/schemas/ProgramApplicantStatus" } }, { "name": "createdAtMin", "in": "query", "description": "Applicants created at or after timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-01T11:59:00" }, "example": "2022-10-01T11:59:00" }, { "name": "createdAtMax", "in": "query", "description": "Applicants created at or before timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-31T11:59:00" }, "example": "2022-10-31T11:59:00" }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/ProgramApplicantSorter" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiProgramApplicantPaginatedResult" } } } } } }, "post": { "tags": [ "ProgramApplicants" ], "summary": "Add a new applicant to a program", "description": "Submits a new applicant to the specified program's application form.\r\nThe applicant's contact information must include at minimum an email, phone, or social handle.\r\n \r\nUse the Status field to indicate whether the applicant should be added as Pending (default) or auto-Approved.\r\nWhen Status is Approved, the applicant is immediately added as an ambassador.\r\n \r\nUse SuppressEmail to prevent sending the notification email when auto-approving.\r\n \r\nSocial network types should be provided as string names (e.g., \"Instagram\", \"TikTok\", \"Twitter\").", "parameters": [ { "name": "program_id", "in": "path", "description": "The program to add the applicant to", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiProgramApplicantPostRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiProgramApplicantPostRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiProgramApplicantPostRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } }, "/v2/programs/{program_id}/applicants/{applicant_id}": { "get": { "tags": [ "ProgramApplicants" ], "summary": "Retrieves the details of a specific applicant", "parameters": [ { "name": "program_id", "in": "path", "description": "The program from which to retrieve the applicant's details", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "applicant_id", "in": "path", "description": "The applicant to be retrieved (contact ID)", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiProgramApplicantDetailsOpenApiResult" } } } } } } }, "/v2/programs/{program_id}/performance": { "get": { "tags": [ "ProgramPerformance" ], "summary": "Retrieves the Program Dashboard for one program: one entry per card on\r\nthe brand's saved dashboard, each with the same figures the portal\r\nshows (time series, period total, and change vs the preceding period).\r\nThe set of metrics mirrors the brand's dashboard configuration.", "parameters": [ { "name": "program_id", "in": "path", "description": "The Program ID", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "fromDate", "in": "query", "description": "Start of the date range (defaults to 30 days ago, matching the dashboard)", "schema": { "type": "string", "format": "date-time" } }, { "name": "toDate", "in": "query", "description": "End of the date range (defaults to now)", "schema": { "type": "string", "format": "date-time" } }, { "name": "metrics", "in": "query", "description": "Optional filter — only return dashboard cards with these metric keys\r\n(e.g. post_emv, members, referred_revenue); omit for the full dashboard", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiProgramPerformanceResponseOpenApiResult" } } } } } } }, "/v2/programs": { "get": { "tags": [ "Programs" ], "summary": "Retrieves a list of programs", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProgramStatus" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiProgramListOpenApiResult" } } } } } } }, "/v2/programs/{program_id}": { "get": { "tags": [ "Programs" ], "summary": "Retrieves a single program", "parameters": [ { "name": "program_id", "in": "path", "description": "The program to retrieve", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiProgramExtendedOpenApiResult" } } } } } } }, "/v2/programs/{program_id}/settings/applicationForm": { "get": { "tags": [ "ProgramSettings" ], "summary": "Retrieves the application form definition for a program", "description": "Returns the application form's settings, custom properties/questions, and supported social networks for the specified program.\r\nUse the property IDs from this response when submitting applicant form values via the POST endpoint.\r\n \r\nTypeIds are returned as string names (e.g., \"Instagram\" instead of 10, \"Radio\" instead of 296).", "parameters": [ { "name": "program_id", "in": "path", "description": "The program for which to retrieve the application form", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiApplicationFormDetailsOpenApiResult" } } } } } } }, "/v2/referral-rewards": { "get": { "tags": [ "ReferralRewards" ], "summary": "Retrieves a list of all referral rewards", "parameters": [ { "name": "ambassadorId", "in": "query", "description": "The ambassador to whom the referral reward was awarded", "schema": { "type": "integer", "format": "int64", "example": 123456 }, "example": 123456 }, { "name": "programId", "in": "query", "description": "The program of the ambassadors from which to retrieve the referral rewards", "schema": { "type": "integer", "format": "int32", "example": 12 }, "example": 12 }, { "name": "attributionId", "in": "query", "description": "Referral rewards resulting from this attribution", "schema": { "type": "integer", "format": "int64", "example": 123456 }, "example": 123456 }, { "name": "rewardType", "in": "query", "description": "Referral rewards of this type. Valid values are: commission, points", "schema": { "$ref": "#/components/schemas/ReferralRewardType" }, "example": "commission" }, { "name": "rewardStatus", "in": "query", "description": "Referral rewards with this status. Valid values are: pending, approved, rejected, paid", "schema": { "$ref": "#/components/schemas/ReferralRewardStatus" }, "example": "pending" }, { "name": "attributionMethod", "in": "query", "description": "Referral rewards based on attribution method. Valid values are: emailAddress, discountCode, referralLink, rewardCode, recurringOrder", "schema": { "$ref": "#/components/schemas/OpenApiAttributionMethod" }, "example": "emailAddress" }, { "name": "createdAtMin", "in": "query", "description": "Referral rewards created at or after timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-31T11:59:00" }, "example": "2022-10-31T11:59:00" }, { "name": "createdAtMax", "in": "query", "description": "Referral rewards created at or before timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-31T11:59:00" }, "example": "2022-10-31T11:59:00" }, { "name": "updatedAtMin", "in": "query", "description": "Referral rewards updated at or after timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-31T11:59:00" }, "example": "2022-10-31T11:59:00" }, { "name": "updatedAtMax", "in": "query", "description": "Referral rewards updated at or before timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-31T11:59:00" }, "example": "2022-10-31T11:59:00" }, { "name": "isPaidTraffic", "in": "query", "description": "Filter referral rewards by the traffic source of the reward's attributed click.\r\ntrue = paid-ad traffic only, false = organic traffic only. Omit for all rewards.", "schema": { "type": "boolean", "example": true }, "example": true }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiReferralRewardPaginatedResultOpenApiResult" } } } } } }, "post": { "tags": [ "ReferralRewards" ], "summary": "Creates a pending manual referral reward", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiReferralRewardPostRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiReferralRewardPostRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiReferralRewardPostRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiReferralRewardOpenApiResult" } } } } } } }, "/v2/referral-rewards/{referral_reward_id}": { "get": { "tags": [ "ReferralRewards" ], "summary": "Retrieves a single referral reward", "parameters": [ { "name": "referral_reward_id", "in": "path", "description": "The referral reward ID", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiReferralRewardOpenApiResult" } } } } } } }, "/v2/referral-rewards/approve": { "post": { "tags": [ "ReferralRewards" ], "summary": "Approves pending referral rewards", "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "text/json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "application/*+json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } }, "/v2/referral-rewards/reject": { "post": { "tags": [ "ReferralRewards" ], "summary": "Rejects pending referral rewards", "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "text/json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "application/*+json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } }, "/v2/referral-rewards/undo": { "post": { "tags": [ "ReferralRewards" ], "summary": "Sets approved or rejected referral rewards back to pending", "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "text/json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "application/*+json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } }, "/v2/referral-rewards/{referralRewardId}": { "put": { "tags": [ "ReferralRewards" ], "summary": "Updates a pending manual referral reward", "parameters": [ { "name": "referralRewardId", "in": "path", "description": "The referral reward id to update", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiReferralRewardPutRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/OpenApiReferralRewardPutRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/OpenApiReferralRewardPutRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiReferralRewardOpenApiResult" } } } } } } }, "/v2/reports/sales-attribution": { "get": { "tags": [ "Reports" ], "summary": "Retrieves the Sales Attribution report: grand totals plus one row per\r\nambassador with activity in the date range (link clicks, new customers,\r\nreferred orders/revenue, commissions and points, personal orders/revenue).\r\nReturns the same figures as the portal's Sales Attribution report.", "parameters": [ { "name": "ambassadorIds", "in": "query", "description": "Only include these ambassadors (contact ids)", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "programIds", "in": "query", "description": "Only include ambassadors in these programs", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "contactOwnerIds", "in": "query", "description": "Only include ambassadors owned by these team members", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "attributionMethods", "in": "query", "description": "Only include attributions via these methods", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiAttributionMethod" } } }, { "name": "tagIds", "in": "query", "description": "Only include ambassadors with these tag ids", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "fromDate", "in": "query", "description": "Start of the reporting date range (inclusive)", "schema": { "type": "string", "format": "date-time" } }, { "name": "toDate", "in": "query", "description": "End of the reporting date range (inclusive)", "schema": { "type": "string", "format": "date-time" } }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/OpenApiSalesAttributionSortField" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiSalesAttributionReportResponsePaginatedResult" } } } } } } }, "/v2/reports/social-posts": { "get": { "tags": [ "Reports" ], "summary": "Retrieves the Social Posts report: grand totals plus one row per\r\nambassador who posted in the date range (post and story counts, reach,\r\nimpressions, engagement, and earned media value). Returns the same\r\nfigures as the portal's Social Posts report.", "parameters": [ { "name": "ambassadorIds", "in": "query", "description": "Only include these ambassadors (contact ids)", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "programIds", "in": "query", "description": "Only include ambassadors in these programs", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "campaignIds", "in": "query", "description": "Only include posts created for these campaigns", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "tagIds", "in": "query", "description": "Only include ambassadors with these tag ids", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "networks", "in": "query", "description": "Only include posts on these networks", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiSocialPostNetwork" } } }, { "name": "fromDate", "in": "query", "description": "Start of the reporting date range (inclusive)", "schema": { "type": "string", "format": "date-time" } }, { "name": "toDate", "in": "query", "description": "End of the reporting date range (inclusive)", "schema": { "type": "string", "format": "date-time" } }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/OpenApiSocialPostsSortField" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiSocialPostsReportResponsePaginatedResult" } } } } } } }, "/v2/rewards/status": { "post": { "tags": [ "Rewards" ], "summary": "Updates the status of manually fulfillable rewards", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardStatusRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/RewardStatusRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/RewardStatusRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiRewardStatusUpdateOpenApiResult" } } } } } } }, "/v2/rewards/{reward_id}": { "get": { "tags": [ "Rewards" ], "summary": "Retrieves a specific reward by id", "parameters": [ { "name": "reward_id", "in": "path", "description": "The reward id", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiRewardOpenApiResult" } } } } } } }, "/v2/rewards": { "get": { "tags": [ "Rewards" ], "summary": "Retrieves a list of all campaign and milestone rewards", "parameters": [ { "name": "ambassador", "in": "query", "description": "Matches rewards owned by the ambassador", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "type", "in": "query", "description": "Filters the list by this type", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RewardType" } } }, { "name": "source", "in": "query", "description": "Filters the list by campaign or milestone source type", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RewardSource" } } }, { "name": "sourceId", "in": "query", "description": "Matches rewards by the campaign or milestone Id", "schema": { "type": "integer", "format": "int64" } }, { "name": "status", "in": "query", "description": "Filters the list by this status", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RewardFulfillmentStatus" } } }, { "name": "createdAtMin", "in": "query", "description": "Rewards created on or after timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-01T11:59:00" }, "example": "2022-10-01T11:59:00" }, { "name": "createdAtMax", "in": "query", "description": "Rewards created on or before timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-31T11:59:00" }, "example": "2022-10-31T11:59:00" }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/RewardSorter" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiCampaignRewardPaginatedResult" } } } } } } }, "/v2/reward-templates": { "get": { "tags": [ "RewardTemplates" ], "summary": "Retrieves a list of reward templates", "parameters": [ { "name": "query", "in": "query", "description": "Searches for reward templates whose name match the search term", "schema": { "type": "string" } }, { "name": "ambassadorIds", "in": "query", "description": "Filter by templates that have rewards assigned to these ambassador(s)", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "rewardTypes", "in": "query", "description": "Filter by reward type", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RewardType" } } }, { "name": "actionRequiredOptions", "in": "query", "description": "Filter by reward templates that require action", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ActionRequired" } } }, { "name": "createdAtMin", "in": "query", "description": "Reward templates created at or after timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time" } }, { "name": "createdAtMax", "in": "query", "description": "Reward templates created at or before timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time" } }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/RewardTemplateSorter" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiRewardTemplateSummaryPaginatedResult" } } } } } } }, "/v2/reward-templates/{reward_template_id}": { "get": { "tags": [ "RewardTemplates" ], "summary": "Retrieves a specific reward template", "parameters": [ { "name": "reward_template_id", "in": "path", "description": "The reward template ID", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiRewardTemplateDetailsOpenApiResult" } } } } } }, "delete": { "tags": [ "RewardTemplates" ], "summary": "Deletes a reward template", "parameters": [ { "name": "reward_template_id", "in": "path", "description": "The reward template ID", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } }, "/v2/reward-templates/{reward_template_id}/rewards": { "get": { "tags": [ "RewardTemplates" ], "summary": "Retrieves the list of rewards for a reward template", "parameters": [ { "name": "reward_template_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "ambassador", "in": "query", "description": "Matches rewards owned by the ambassador", "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "status", "in": "query", "description": "Filters the list by this status", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RewardFulfillmentStatus" } } }, { "name": "createdAtMin", "in": "query", "description": "Reward created on or after timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-01T11:59:00" }, "example": "2022-10-01T11:59:00" }, { "name": "createdAtMax", "in": "query", "description": "Reward created on or before timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-31T11:59:00" }, "example": "2022-10-31T11:59:00" }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 }, { "name": "sortField", "in": "query", "description": "Sort results by the provided value", "schema": { "$ref": "#/components/schemas/RewardSorter" } }, { "name": "sortDirection", "in": "query", "description": "The direction the results are sorted", "schema": { "$ref": "#/components/schemas/SortDirections" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiRewardPaginatedResult" } } } } } } }, "/v2/social-posts": { "get": { "tags": [ "SocialPosts" ], "summary": "Recent individual posts where ambassadors mentioned the brand — the\r\nportal's Social Feed: post URL and media, caption, platform, post type,\r\nambassador, program, posted date, engagement metrics, and per-post EMV.\r\nDistinct from /v2/community/posts (community-forum posts).", "parameters": [ { "name": "networks", "in": "query", "description": "Only include posts on these networks", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiSocialPostNetwork" } } }, { "name": "programIds", "in": "query", "description": "Only include posts by ambassadors in these programs", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } }, { "name": "contactId", "in": "query", "description": "Only include posts by this ambassador (contact id)", "schema": { "type": "integer", "format": "int64" } }, { "name": "fromDate", "in": "query", "description": "Start of the date range (inclusive)", "schema": { "type": "string", "format": "date-time" } }, { "name": "toDate", "in": "query", "description": "End of the date range (inclusive)", "schema": { "type": "string", "format": "date-time" } }, { "name": "sort", "in": "query", "description": "Sort order", "schema": { "$ref": "#/components/schemas/OpenApiSocialFeedSort" } }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiSocialFeedPostPaginatedResult" } } } } } } }, "/v2/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "Retrieves a list of all webhooks", "parameters": [ { "name": "address", "in": "query", "description": "Filter webhooks that send POST requests to this URI.", "schema": { "type": "string", "example": "`https://my.app.com/webhook/listener`" }, "example": "`https://my.app.com/webhook/listener`" }, { "name": "topic", "in": "query", "description": "Filter webhooks subscribed to a given topic.", "schema": { "type": "string", "example": "'reward/redeemed'" }, "example": "'reward/redeemed'" }, { "name": "createdAtMin", "in": "query", "description": "Events created at or after timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-01T11:59:00" }, "example": "2022-10-01T11:59:00" }, { "name": "createdAtMax", "in": "query", "description": "Events created at or before timestamp. Date ISO 8601", "schema": { "type": "string", "format": "date-time", "example": "2022-10-01T11:59:00" }, "example": "2022-10-01T11:59:00" }, { "name": "pageIndex", "in": "query", "description": "The page index", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32", "example": 1 }, "example": 1 }, { "name": "pageSize", "in": "query", "description": "The record count to return per page", "schema": { "type": "integer", "format": "int32", "example": 20 }, "example": 20 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiWebhookPaginatedResult" } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Creates a new webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWebhookPostRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UserWebhookPostRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UserWebhookPostRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiWebhookOpenApiResult" } } } } } } }, "/v2/webhooks/{webhook_id}": { "get": { "tags": [ "Webhooks" ], "summary": "Retrieves a specific webhook", "parameters": [ { "name": "webhook_id", "in": "path", "description": "The event ID", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiWebhookOpenApiResult" } } } } } }, "put": { "tags": [ "Webhooks" ], "summary": "Updates an existing webhook", "parameters": [ { "name": "webhook_id", "in": "path", "description": "The webhook ID", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWebhookPutRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UserWebhookPutRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UserWebhookPutRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiWebhookOpenApiResult" } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Deletes an existing webhook", "parameters": [ { "name": "webhook_id", "in": "path", "description": "The webhook ID", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiResult" } } } } } } } }, "components": { "schemas": { "AccountCustomer": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "nullable": true }, "accountId": { "type": "integer", "format": "int64", "nullable": true }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "sourceUniqueId": { "type": "string", "nullable": true }, "sourceCreateDate": { "type": "string", "format": "date-time", "nullable": true }, "sourceAuthTokenId": { "type": "integer", "format": "int64", "nullable": true }, "ordersCount": { "type": "integer", "format": "int32" }, "totalSpent": { "type": "number", "format": "double", "nullable": true }, "order": { "$ref": "#/components/schemas/Order" }, "orders": { "type": "array", "items": { "$ref": "#/components/schemas/Order" }, "nullable": true }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/Address" }, "nullable": true }, "sourceAuthToken": { "$ref": "#/components/schemas/Token" }, "modifyUser": { "type": "integer", "format": "int64" }, "addressData": { "type": "string", "nullable": true }, "orderData": { "type": "string", "nullable": true }, "lastSyncDate": { "type": "string", "format": "date-time", "nullable": true }, "tags": { "type": "string", "nullable": true } }, "additionalProperties": false }, "AccountProgram": { "type": "object", "properties": { "programId": { "type": "integer", "format": "int32" }, "statusId": { "type": "integer", "format": "int32" }, "statusDate": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "AccountReferralLinkId": { "type": "object", "properties": { "referralLinkId": { "type": "integer", "format": "int64", "nullable": true }, "typeId": { "type": "integer", "format": "int32", "nullable": true }, "code": { "type": "string", "nullable": true }, "createDate": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false }, "AccountSocialPost": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "content": { "type": "string", "nullable": true }, "link": { "type": "string", "nullable": true }, "imageUri": { "type": "string", "nullable": true }, "likeCount": { "type": "integer", "format": "int32" }, "commentCount": { "type": "integer", "format": "int32" }, "postDate": { "type": "string", "format": "date-time" }, "location": { "type": "string", "nullable": true }, "latitude": { "type": "number", "format": "double", "nullable": true }, "longitude": { "type": "number", "format": "double", "nullable": true }, "postTags": { "type": "array", "items": { "$ref": "#/components/schemas/PostTag" }, "nullable": true }, "hashtags": { "type": "array", "items": { "type": "string" }, "nullable": true }, "valueRaw": { "type": "string", "nullable": true }, "mediaProductType": { "$ref": "#/components/schemas/MediaProductType" }, "videoViews": { "type": "integer", "format": "int32", "nullable": true }, "uniqueImpressions": { "type": "integer", "format": "int32", "nullable": true }, "totalImpressions": { "type": "integer", "format": "int32", "nullable": true }, "saved": { "type": "integer", "format": "int32", "nullable": true }, "shares": { "type": "integer", "format": "int32", "nullable": true }, "reachSourceId": { "type": "integer", "format": "int32", "nullable": true }, "thumbnailUri": { "type": "string", "nullable": true }, "replaysCount": { "type": "integer", "format": "int32", "nullable": true }, "aggPlaysCount": { "type": "integer", "format": "int32", "nullable": true }, "avgWatchTime": { "type": "integer", "format": "int64", "nullable": true }, "totalWatchTime": { "type": "integer", "format": "int64", "nullable": true } }, "additionalProperties": false }, "AccountSocialProfile": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "accountId": { "type": "integer", "format": "int64" }, "userId": { "type": "integer", "format": "int64" }, "uniqueId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "displayName": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true }, "profileUri": { "type": "string", "nullable": true }, "imageUri": { "type": "string", "nullable": true }, "externalImageUri": { "type": "string", "nullable": true }, "resourceId": { "type": "integer", "format": "int64", "nullable": true }, "location": { "type": "string", "nullable": true }, "dataSourceUserId": { "type": "integer", "format": "int64", "nullable": true }, "dataSourceType": { "$ref": "#/components/schemas/Lookup" }, "stats": { "$ref": "#/components/schemas/AccountStats" }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/AccountSocialPost" }, "nullable": true }, "lastFullSyncDate": { "type": "string", "format": "date-time", "nullable": true }, "removeAndArchive": { "type": "boolean" }, "isFollower": { "type": "boolean" }, "isFollowing": { "type": "boolean" }, "hasTokenConnected": { "type": "boolean" }, "isExpired": { "type": "boolean" }, "typeId": { "type": "integer", "format": "int32" }, "type": { "$ref": "#/components/schemas/Lookup" }, "network": { "type": "string", "nullable": true, "readOnly": true }, "socialNetwork": { "$ref": "#/components/schemas/SocialNetwork" }, "profileTypeId": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false }, "AccountStats": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "networkId": { "type": "integer", "format": "int32" }, "followedByCount": { "type": "integer", "format": "int64", "nullable": true }, "followsCount": { "type": "integer", "format": "int64", "nullable": true }, "statusesCount": { "type": "integer", "format": "int64", "nullable": true }, "viewsCount": { "type": "integer", "format": "int64", "nullable": true }, "engagement": { "type": "number", "format": "double", "nullable": true }, "averageEngagement": { "type": "number", "format": "double" }, "avgLikes": { "type": "number", "format": "float", "nullable": true }, "avgComments": { "type": "number", "format": "float", "nullable": true }, "postFrequency": { "type": "number", "format": "float", "nullable": true }, "score": { "type": "number", "format": "double", "nullable": true }, "totalReach": { "type": "integer", "format": "int64", "nullable": true }, "followers": { "type": "array", "items": { "$ref": "#/components/schemas/UserAccount" }, "nullable": true }, "socialProfile": { "$ref": "#/components/schemas/AccountSocialProfile" }, "network": { "type": "string", "nullable": true, "readOnly": true }, "hasStats": { "type": "boolean", "readOnly": true } }, "additionalProperties": false }, "ActionRequired": { "enum": [ "needsManualFulfillment" ], "type": "string" }, "Address": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "accountId": { "type": "integer", "format": "int64" }, "address1": { "type": "string", "nullable": true }, "address2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "province": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "countryId": { "type": "integer", "format": "int32", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "isDefault": { "type": "boolean" }, "phone": { "type": "string", "nullable": true }, "modifyUser": { "type": "integer", "format": "int64" }, "connectionUserId": { "type": "integer", "format": "int64" }, "location": { "type": "string", "nullable": true, "readOnly": true }, "hasAddress": { "type": "boolean", "readOnly": true } }, "additionalProperties": false }, "ApprovalMethod": { "enum": [ "manual", "auto_approve" ], "type": "string", "description": "Defines the approval method for rewards." }, "AssignedCodeImport": { "required": [ "code" ], "type": "object", "properties": { "code": { "minLength": 1, "type": "string", "description": "The code to import.", "example": "abc_CODE" }, "email": { "type": "string", "description": "The email address of the ambassador to whom the code will be assigned.", "nullable": true, "example": "superman@rosterheros.com" }, "ambassadorId": { "type": "integer", "description": "The ambassador to whom the code will be assigned.", "format": "int64", "nullable": true, "example": 123456 } }, "additionalProperties": false }, "AssignedCodeImportRequest": { "required": [ "codes" ], "type": "object", "properties": { "codes": { "type": "array", "items": { "$ref": "#/components/schemas/AssignedCodeImport" }, "description": "Codes list to import." } }, "additionalProperties": false }, "Authentication": { "type": "object", "properties": { "network": { "$ref": "#/components/schemas/SocialNetwork" }, "token": { "type": "string", "nullable": true }, "tokenSecret": { "type": "string", "nullable": true }, "authVerifier": { "type": "string", "nullable": true }, "redirectUri": { "type": "string", "nullable": true }, "sourceUniqueId": { "type": "string", "nullable": true }, "userId": { "type": "integer", "format": "int64" }, "sessionUserId": { "type": "integer", "format": "int64" }, "state": { "type": "string", "nullable": true }, "udfValues": { "type": "object", "additionalProperties": { "nullable": true }, "nullable": true }, "expiresIn": { "type": "integer", "format": "int64", "nullable": true }, "accessExpiresIn": { "type": "integer", "format": "int64", "nullable": true }, "apiUrl": { "type": "string", "nullable": true }, "permissions": { "type": "string", "nullable": true }, "codeChallenge": { "type": "string", "nullable": true }, "codeChallengeVerifier": { "type": "string", "nullable": true }, "userToken": { "$ref": "#/components/schemas/Token" } }, "additionalProperties": false }, "AutomatedRewardTemplateStats": { "type": "object", "properties": { "eligibleCount": { "type": "integer", "format": "int32" }, "awardedCount": { "type": "integer", "format": "int32" }, "notRedeemedCount": { "type": "integer", "format": "int32" }, "redeemedCount": { "type": "integer", "format": "int32" }, "fulfilledOrdersCount": { "type": "integer", "format": "int32" }, "unfulfilledOrdersCount": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "CampaignActionRequired": { "enum": [ "needs_approval", "needs_fulfillment" ], "type": "string" }, "CampaignParticipantsSorter": { "enum": [ "ambassador", "submissions", "lastSubmission", "reach", "likes", "comments", "engagement", "progress", "emv", "impressions" ], "type": "string" }, "CampaignParticipantsStatus": { "enum": [ "joined", "invite_opened", "invite_sent", "invite_not_sent", "reminder_sent", "completed", "unsubscribed", "not_interested" ], "type": "string" }, "CampaignRewardIssuance": { "enum": [ "upon_joining_campaign", "upon_completing_campaign" ], "type": "string" }, "CampaignSorter": { "enum": [ "status", "name", "publishDate", "joinedCount", "completedCount", "participationRate", "needsApprovalCount", "needsFulfillmentCount" ], "type": "string" }, "CampaignStatus": { "enum": [ "draft", "active", "completed", "planned", "archived", "published" ], "type": "string" }, "CampaignType": { "enum": [ "invite_only", "public_hashtag" ], "type": "string" }, "CashRewardSorter": { "enum": [ "earnedDate", "amount", "ambassador" ], "type": "string" }, "CashRewardSource": { "enum": [ "milestone", "campaign", "manual" ], "type": "string" }, "CashRewardStatus": { "enum": [ "pending", "approved", "paid", "rejected" ], "type": "string" }, "ChannelPostAuthorType": { "enum": [ "teamMembers", "teamMembersPlusParticipants" ], "type": "string" }, "ChannelSorter": { "enum": [ "name", "participants", "posts", "comments", "latestActivity" ], "type": "string" }, "ChannelStatus": { "enum": [ "draft", "active", "archived" ], "type": "string" }, "CommentPostRequest": { "type": "object", "properties": { "parentId": { "type": "integer", "format": "int32" }, "parentType": { "$ref": "#/components/schemas/ParentType" }, "userId": { "type": "integer", "format": "int64", "nullable": true }, "message": { "type": "string", "nullable": true } }, "additionalProperties": false }, "CommunityPostsSorting": { "enum": [ "post", "channel", "uniqueViews", "likes", "comments", "updated", "latestActivity", "created" ], "type": "string" }, "ContactImportOptions": { "type": "object", "properties": { "overwriteExisting": { "type": "boolean", "description": "Whether to overwrite existing contact data when a match is found", "example": false }, "importTagName": { "type": "string", "description": "The name of the import tag to add to all imported contacts. Leave empty to skip tagging.", "nullable": true, "example": "Imported 2026-01-08 14:30" } }, "additionalProperties": false, "description": "Import options for contact import" }, "ContactImportRequest": { "required": [ "options", "rows" ], "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The rows of contact data to import. Each row is a dictionary of column header to value.", "example": [ { "Email Address": "alex@example.com", "First Name": "Alex" } ] }, "options": { "$ref": "#/components/schemas/ContactImportOptions" } }, "additionalProperties": false, "description": "Request model for creating a contact import" }, "ContactImportResponse": { "type": "object", "properties": { "taskId": { "type": "integer", "description": "The task ID for the import job", "format": "int64", "example": 12345 }, "userListId": { "type": "integer", "description": "The user list ID containing the import data", "format": "int64", "example": 67890 }, "status": { "$ref": "#/components/schemas/ContactImportStatus" }, "rowCount": { "type": "integer", "description": "The number of rows in the import", "format": "int32", "example": 500 }, "message": { "type": "string", "description": "A message describing the import status", "nullable": true, "example": "Your import is being processed. You will receive an email when the processing is done." }, "validationErrors": { "description": "Validation error details when status is ValidationFailed. Null for successful imports.", "nullable": true } }, "additionalProperties": false, "description": "Response model for contact import creation" }, "ContactImportResponseOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/ContactImportResponse" } }, "additionalProperties": false }, "ContactImportStatus": { "enum": [ "queued", "processing", "completed", "failed", "needsReview", "validationFailed" ], "type": "string", "description": "Status of a contact import job" }, "CreateCodeRequest": { "required": [ "ambassadorId", "code" ], "type": "object", "properties": { "code": { "minLength": 1, "type": "string", "description": "The code to be created", "example": "abc_CODE" }, "ambassadorId": { "type": "integer", "description": "The ambassador to whom the code will be assigned", "format": "int64", "example": 123456 } }, "additionalProperties": false }, "CreatePostStatus": { "enum": [ "draft", "published" ], "type": "string" }, "Currency": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "alpha3": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } }, "additionalProperties": false }, "CustomerDiscount": { "type": "object", "properties": { "ruleType": { "$ref": "#/components/schemas/SmartLinkDiscountTypes" }, "discountPrefix": { "type": "string", "description": "The prefix used for generated discount codes (e.g., \"ROSTER\").", "nullable": true }, "discountType": { "$ref": "#/components/schemas/DiscountTypes" }, "discountAmount": { "type": "number", "description": "The discount amount. For percentage, this is a number (e.g., 10 for 10%). \r\nFor fixed_amount, this is the monetary value.", "format": "double", "nullable": true }, "discountRuleId": { "type": "integer", "description": "The ID of the discount rule in the system, if applicable.", "format": "int64", "nullable": true } }, "additionalProperties": false, "description": "Represents the customer discount configuration for a smart link." }, "DiscounCodeStatus": { "enum": [ "active", "deactivated", "expired" ], "type": "string", "description": "The discount code status" }, "DiscountCode": { "type": "object", "properties": { "code": { "type": "string", "nullable": true }, "discountRuleId": { "type": "integer", "format": "int64" }, "typeId": { "type": "integer", "format": "int32" }, "active": { "type": "boolean" } }, "additionalProperties": false }, "DiscountCodeSorter": { "enum": [ "code", "status", "createdAt", "ambassador", "uses", "revenue" ], "type": "string" }, "DiscountRuleSorter": { "enum": [ "title", "startDate", "status", "discountAmount", "assigned", "uses", "revenue" ], "type": "string" }, "DiscountTypes": { "enum": [ "fixed_amount", "percentage", "free_shipping" ], "type": "string", "description": "The type of discount rule discount" }, "Emoji": { "type": "object", "properties": { "unified": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } }, "additionalProperties": false }, "EventSorter": { "enum": [ "createdAt" ], "type": "string" }, "EventSubjectType": { "enum": [ "reward", "attribution", "milestoneReward", "referralReward" ], "type": "string" }, "EventVerbType": { "enum": [ "redeemed", "created", "updated", "deleted" ], "type": "string" }, "ExternalOrderSource": { "enum": [ "none", "shopify", "api", "scriptTag" ], "type": "string" }, "ImageIcon": { "type": "object", "properties": { "name": { "type": "string", "nullable": true } }, "additionalProperties": false }, "ImportStatusResponse": { "type": "object", "properties": { "hasActiveImport": { "type": "boolean", "description": "Whether the brand has an active import in progress", "example": false } }, "additionalProperties": false, "description": "Response model for import status check" }, "ImportStatusResponseOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/ImportStatusResponse" } }, "additionalProperties": false }, "LikePostRequest": { "type": "object", "properties": { "parentId": { "type": "integer", "format": "int32" }, "parentType": { "$ref": "#/components/schemas/ParentType" }, "userId": { "type": "integer", "format": "int64", "nullable": true } }, "additionalProperties": false }, "LinkedObject": { "type": "object", "properties": { "id": { "type": "integer", "description": "Related object Id", "format": "int64", "example": 1111 }, "name": { "type": "string", "description": "Related object Name", "nullable": true, "example": "Name" } }, "additionalProperties": false }, "Lookup": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "lookupType": { "type": "string", "nullable": true }, "descr": { "type": "string", "nullable": true }, "value": { "type": "string", "nullable": true }, "sequence": { "type": "integer", "format": "int32", "nullable": true }, "active": { "type": "boolean" } }, "additionalProperties": false }, "ManualRewardTemplateStats": { "type": "object", "properties": { "eligibleCount": { "type": "integer", "format": "int32" }, "awardedCount": { "type": "integer", "format": "int32" }, "needsFulfillmentCount": { "type": "integer", "format": "int32" }, "fulfilledCount": { "type": "integer", "format": "int32" }, "wontFulfillCount": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "MediaProductType": { "enum": [ "feed", "story", "reels" ], "type": "string" }, "MilestoneRewardSorter": { "enum": [ "ambassador", "dateUnlocked", "createdAt" ], "type": "string" }, "MilestoneSeriesParticipantsSorter": { "enum": [ "ambassador", "currentMilestone", "unlockedDate", "latestPoints" ], "type": "string" }, "OpenApiAddress": { "type": "object", "properties": { "street": { "type": "string", "description": "The street of the address", "nullable": true, "example": "First Street, 1" }, "street2": { "type": "string", "description": "Apartment, suite, etc of the address", "nullable": true, "example": "APT # 4" }, "city": { "type": "string", "description": "The city of the address", "nullable": true, "example": "Lehi" }, "province": { "type": "string", "description": "The province of the address", "nullable": true, "example": "Utah" }, "postalCode": { "type": "string", "description": "The postal code of the address", "nullable": true, "example": "84043" }, "country": { "type": "string", "description": "The alpha-3 country code of the address. (ie: USA)", "nullable": true, "example": "United States" } }, "additionalProperties": false }, "OpenApiApplicantPaymentMethod": { "required": [ "type", "value" ], "type": "object", "properties": { "type": { "minLength": 1, "type": "string", "description": "The payment method type. Use the method types returned by the form definition endpoint (e.g., \"PayPal\", \"Venmo\").", "example": "PayPal" }, "value": { "minLength": 1, "type": "string", "description": "The payout identifier for the payment method (e.g., PayPal email, Venmo handle)", "example": "jane.doe@paypal.com" } }, "additionalProperties": false, "description": "Payment method for an applicant" }, "OpenApiApplicantProperty": { "required": [ "propertyId", "value" ], "type": "object", "properties": { "propertyId": { "type": "integer", "description": "The form property ID from the form definition", "format": "int64", "example": 758 }, "value": { "description": "The value for this property" } }, "additionalProperties": false, "description": "Value for a custom form property" }, "OpenApiApplicantSocialProfile": { "required": [ "handle", "networkType" ], "type": "object", "properties": { "networkType": { "minLength": 1, "type": "string", "description": "The social network type name", "example": "Instagram" }, "handle": { "minLength": 1, "type": "string", "description": "The social media handle", "example": "janedoe" } }, "additionalProperties": false, "description": "Social profile for an applicant" }, "OpenApiApplicantStatus": { "enum": [ "pending", "approved" ], "type": "string", "description": "The initial status for the applicant" }, "OpenApiApplicationFormDetails": { "type": "object", "properties": { "name": { "type": "string", "description": "The application form name", "nullable": true, "example": "Become a Brand Ambassador" }, "descr": { "type": "string", "description": "The application form description (HTML)", "nullable": true, "example": "
Apply to become an ambassador...
" }, "settings": { "description": "The form settings including field visibility, validation rules, and branding", "nullable": true }, "properties": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiApplicationFormProperty" }, "description": "The custom properties/questions on the application form", "nullable": true }, "supportedNetworks": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiApplicationFormNetwork" }, "description": "The social networks supported by the application form", "nullable": true } }, "additionalProperties": false, "description": "Application form details including settings, custom properties, and supported networks" }, "OpenApiApplicationFormDetailsOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiApplicationFormDetails" } }, "additionalProperties": false }, "OpenApiApplicationFormNetwork": { "type": "object", "properties": { "networkType": { "type": "string", "description": "The social network type", "nullable": true, "example": "Instagram" }, "descr": { "type": "string", "description": "The description of the social network", "nullable": true, "example": "Instagram" }, "prefix": { "type": "string", "description": "The URL prefix for the social network", "nullable": true, "example": "https://instagram.com/" } }, "additionalProperties": false, "description": "A social network supported by the application form" }, "OpenApiApplicationFormProperty": { "type": "object", "properties": { "id": { "type": "integer", "description": "The form property ID (use this as PropertyId when submitting an applicant)", "format": "int64", "example": 758 }, "sequence": { "type": "integer", "description": "The display order of this property on the form", "format": "int32", "example": 1 }, "property": { "$ref": "#/components/schemas/OpenApiApplicationFormPropertyDef" } }, "additionalProperties": false, "description": "A custom property/question on the application form" }, "OpenApiApplicationFormPropertyDef": { "type": "object", "properties": { "id": { "type": "integer", "description": "The property definition ID", "format": "int64", "example": 446 }, "type": { "type": "string", "description": "The property field type", "nullable": true, "example": "Radio" }, "label": { "type": "string", "description": "The display label for the property", "nullable": true, "example": "Have you purchased from us before?" }, "settings": { "description": "Property settings including dropdown/radio options", "nullable": true }, "validations": { "description": "Validation rules for the property", "nullable": true } }, "additionalProperties": false, "description": "Property definition with type, label, and validation" }, "OpenApiAttribution": { "type": "object", "properties": { "attributionId": { "type": "integer", "description": "The attribution ID", "format": "int64", "nullable": true, "example": 123456 }, "attributionType": { "$ref": "#/components/schemas/OpenApiAttributionType" }, "attributionMethod": { "$ref": "#/components/schemas/OpenApiAttributionMethod" }, "attributionStatus": { "$ref": "#/components/schemas/OpenApiAttributionStatus" }, "order": { "$ref": "#/components/schemas/OpenApiOrder" }, "ambassador": { "$ref": "#/components/schemas/OpenApiContactBase" }, "attributionSource": { "description": "The attribution source.", "nullable": true }, "newCustomer": { "type": "boolean", "description": "In case of new customer - true, othewise - false", "nullable": true }, "createdAt": { "type": "string", "description": "The date the attribution was created", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "updatedAt": { "type": "string", "description": "The date the attribution was modified", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "linkClick": { "$ref": "#/components/schemas/OpenApiLinkClick" } }, "additionalProperties": false }, "OpenApiAttributionMethod": { "enum": [ "emailAddress", "rewardCode", "referralLink", "discountCode", "recurringOrder" ], "type": "string" }, "OpenApiAttributionOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiAttribution" } }, "additionalProperties": false }, "OpenApiAttributionResponse": { "type": "object", "properties": { "summary": { "$ref": "#/components/schemas/OpenApiAttributionSummary" }, "attributions": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiAttribution" }, "nullable": true } }, "additionalProperties": false }, "OpenApiAttributionResponsePaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiAttributionResponse" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiAttributionStatus": { "enum": [ "rejected", "active" ], "type": "string" }, "OpenApiAttributionSummary": { "type": "object", "properties": { "totalRevenue": { "type": "number", "format": "double" }, "totalClicks": { "type": "integer", "format": "int32" }, "totalDiscounts": { "type": "integer", "format": "int32" }, "totalRecurring": { "type": "integer", "format": "int32" }, "newCustomers": { "type": "integer", "format": "int32" }, "totalEmails": { "type": "integer", "format": "int32" }, "totalRewards": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "OpenApiAttributionType": { "enum": [ "referral", "personal" ], "type": "string" }, "OpenApiAuthor": { "type": "object", "properties": { "userId": { "type": "integer", "description": "The ID of the author", "format": "int64", "example": 1234 }, "contactId": { "type": "integer", "description": "The Contact ID of the author", "format": "int64", "nullable": true, "example": 1234 }, "firstName": { "type": "string", "description": "The first name of the author", "nullable": true, "example": "1234" }, "lastName": { "type": "string", "description": "The last name of the author", "nullable": true, "example": "1234" }, "email": { "type": "string", "description": "The email of the author", "nullable": true, "example": "1234" }, "communityProfile": { "$ref": "#/components/schemas/OpenApiCommunityProfile" } }, "additionalProperties": false }, "OpenApiCampaign": { "type": "object", "properties": { "id": { "type": "integer", "description": "The campaign ID", "format": "int64", "example": 123456 }, "type": { "$ref": "#/components/schemas/CampaignType" }, "name": { "type": "string", "description": "The name of the campaign", "nullable": true, "example": "My Campaign" }, "publishAt": { "type": "string", "description": "Date of campaign publishing", "format": "date-time", "nullable": true, "example": "2022-10-20T09:18:38.33" }, "startAt": { "type": "string", "description": "Date of campaign starting", "format": "date-time", "nullable": true, "example": "2022-10-20T09:18:38.33" }, "endAt": { "type": "string", "description": "Date of campaign ending", "format": "date-time", "nullable": true, "example": "2022-10-20T09:18:38.33" }, "joinByDate": { "type": "string", "description": "Date after which no additional ambassadors can join this campaign. Existing participants are unaffected.", "format": "date-time", "nullable": true, "example": "2022-10-20T09:18:38.33" }, "participantLimit": { "type": "integer", "description": "Maximum number of ambassadors allowed to join this campaign. When set and reached, new joins are rejected. NULL = unlimited.", "format": "int32", "nullable": true, "example": 25 }, "joinedCount": { "type": "integer", "description": "Current count of ambassadors who have joined the campaign (JoinedDate IS NOT NULL). Counts toward ParticipantLimit.", "format": "int32", "nullable": true, "example": 18 }, "status": { "$ref": "#/components/schemas/CampaignStatus" }, "title": { "type": "string", "description": "The title of campaign", "nullable": true, "example": "Winter campaign!" }, "campaignStats": { "$ref": "#/components/schemas/OpenApiCampaignStats" }, "createdAt": { "type": "string", "description": "Date of campaign creation", "format": "date-time", "nullable": true, "example": "2022-10-20T09:18:38.33" }, "updatedAt": { "type": "string", "description": "Date when campaign gas been updated", "format": "date-time", "nullable": true, "example": "2022-10-20T09:18:38.33" } }, "additionalProperties": false }, "OpenApiCampaignContent": { "type": "object", "properties": { "posts": { "type": "integer", "format": "int32" }, "stories": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "OpenApiCampaignFunnel": { "type": "object", "properties": { "added": { "type": "integer", "format": "int32" }, "joined": { "type": "integer", "format": "int32" }, "completed": { "type": "integer", "format": "int32" }, "participationRate": { "type": "number", "format": "double" } }, "additionalProperties": false }, "OpenApiCampaignPaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiCampaign" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiCampaignParticipant": { "type": "object", "properties": { "campaignId": { "type": "integer", "description": "The campaign ID", "format": "int64", "example": 123456 }, "participant": { "$ref": "#/components/schemas/OpenApiContactProgramBase" }, "status": { "$ref": "#/components/schemas/CampaignParticipantsStatus" }, "statusDate": { "type": "string", "description": "Date of participation status", "format": "date-time", "nullable": true, "example": "2022-10-20T09:18:38.33" }, "submissionsCount": { "type": "integer", "description": "Participant number of submissions in the campaign", "format": "int32", "example": 8 }, "lastSubmissionDate": { "type": "string", "description": "Date of the last participant submission in the campaign", "format": "date-time", "nullable": true, "example": "2022-10-22T09:18:38.33" }, "postsStats": { "$ref": "#/components/schemas/OpenApiParticipantPostStats" }, "progress": { "type": "number", "description": "Participant progress percentage in the campaign", "format": "double", "example": 54.4 }, "address": { "$ref": "#/components/schemas/OpenApiAddress" } }, "additionalProperties": false }, "OpenApiCampaignParticipantPaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiCampaignParticipant" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiCampaignPerformanceInfo": { "type": "object", "properties": { "campaignId": { "type": "integer", "format": "int64" }, "name": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "startAt": { "type": "string", "format": "date-time" }, "endAt": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false }, "OpenApiCampaignPerformanceResponse": { "type": "object", "properties": { "campaign": { "$ref": "#/components/schemas/OpenApiCampaignPerformanceInfo" }, "funnel": { "$ref": "#/components/schemas/OpenApiCampaignFunnel" }, "content": { "$ref": "#/components/schemas/OpenApiCampaignContent" }, "social": { "$ref": "#/components/schemas/OpenApiCampaignSocial" }, "rewards": { "$ref": "#/components/schemas/OpenApiCampaignRewards" } }, "additionalProperties": false }, "OpenApiCampaignPerformanceResponseOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiCampaignPerformanceResponse" } }, "additionalProperties": false }, "OpenApiCampaignReward": { "type": "object", "properties": { "id": { "type": "integer", "description": "The reward ID", "format": "int64", "example": 123456 }, "ambassador": { "$ref": "#/components/schemas/OpenApiContactProgramBase" }, "type": { "$ref": "#/components/schemas/RewardType" }, "status": { "$ref": "#/components/schemas/RewardFulfillmentStatus" }, "rewardStatusId": { "type": "integer", "description": "The raw status id. Reward statuses come from two deliberately separate value spaces:\r\nfulfilment (601 Pending / 276 Fulfilled / 602 Won't fulfill / 894 Redeemed / 895 Not\r\nredeemed / 1258 Redemption failed) and money (530 Pending / 536 Approved / 537 Paid /\r\n538 Rejected). Cash rewards use the money ladder, so App.OpenApi.Domain.Models.Base.Engagement.Rewards.OpenApiRewardBase.Status cannot represent\r\nthem - branch on the reward type and read this instead.", "format": "int32", "example": 530 }, "cashAmount": { "type": "number", "description": "The cash value of this reward, or null when it is not a cash reward. Null is the\r\ndiscriminator: a points or product reward has no amount at all, which is different from an\r\namount of zero, and must never be rendered as money.", "format": "double", "nullable": true, "example": 50 }, "statusDate": { "type": "string", "description": "The date the status was modified", "format": "date-time", "nullable": true }, "rewardTemplate": { "$ref": "#/components/schemas/OpenApiRewardTemplate" }, "discountCode": { "$ref": "#/components/schemas/OpenApiRewardDiscountCode" }, "order": { "$ref": "#/components/schemas/OpenApiRewardOrder" }, "createdAt": { "type": "string", "description": "The timestamp the reward was created", "format": "date-time", "example": "2022-10-31T11:59:00" }, "updatedAt": { "type": "string", "description": "The most recent timestamp the reward was updated", "format": "date-time", "example": "2022-10-31T11:59:00" }, "campaignId": { "type": "integer", "format": "int64" }, "address": { "$ref": "#/components/schemas/OpenApiAddress" }, "customProperties": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiRewardCustomProperty" }, "nullable": true } }, "additionalProperties": false }, "OpenApiCampaignRewardPaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiCampaignReward" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiCampaignRewards": { "type": "object", "properties": { "needsApproval": { "type": "integer", "format": "int32" }, "needsFulfillment": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "OpenApiCampaignSocial": { "type": "object", "properties": { "followerReach": { "type": "integer", "format": "int64" }, "engagement": { "type": "number", "format": "double" }, "engagementRate": { "type": "number", "format": "double" }, "emv": { "type": "number", "format": "double" } }, "additionalProperties": false }, "OpenApiCampaignStats": { "type": "object", "properties": { "socialPostsCount": { "type": "integer", "format": "int32" }, "reach": { "type": "integer", "format": "int64" }, "engagementRate": { "type": "number", "format": "double" }, "addedCount": { "type": "integer", "format": "int32" }, "invitedCount": { "type": "integer", "format": "int32" }, "joinedCount": { "type": "integer", "format": "int32" }, "participantLimit": { "type": "integer", "format": "int32", "nullable": true }, "completedCount": { "type": "integer", "format": "int32" }, "participationRate": { "type": "number", "format": "double" }, "completionRate": { "type": "number", "format": "double", "readOnly": true }, "needsApprovalCount": { "type": "integer", "format": "int32" }, "needsFulfillmentCount": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "OpenApiCaptureClickParams": { "type": "object", "properties": { "referralLinkId": { "type": "string", "description": "The referral identifier from the referral link (e.g. in the referral link `https://example.com/?rstr=123abc`, the referral ID is `123abc`", "nullable": true, "example": "123abc" }, "landingPageUrl": { "type": "string", "description": "The current page where the click was captured", "nullable": true, "example": "https://example.com" }, "referrerUrl": { "type": "string", "description": "The http referrer", "nullable": true, "example": "`https://example.com`" }, "utmParams": { "description": "A JSON object of all UTM params from landing page URL", "nullable": true }, "queryParams": { "description": "A JSON object of all URL params from the landing page URL", "nullable": true }, "userAgent": { "type": "string", "description": "The HTTP User Agent", "nullable": true, "example": "Mozilla/5.0 () () " } }, "additionalProperties": false }, "OpenApiChannel": { "type": "object", "properties": { "channelId": { "type": "integer", "description": "The channel ID", "format": "int64", "nullable": true, "example": 1254 }, "name": { "type": "string", "description": "The channel name", "nullable": true, "example": "Ambassadors" }, "theme": { "$ref": "#/components/schemas/OpenApiChannelTheme" }, "description": { "type": "string", "description": "The channel description", "nullable": true, "example": "Enjoy your time here" }, "status": { "$ref": "#/components/schemas/ChannelStatus" }, "postAuthorType": { "$ref": "#/components/schemas/ChannelPostAuthorType" }, "programs": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiChannelProgram" }, "description": "List of programs that have auto-add enabled.", "nullable": true }, "visibility": { "$ref": "#/components/schemas/VisibilityChannelType" }, "systemChannel": { "type": "boolean", "description": "The channel is created by system", "example": 45 }, "stats": { "$ref": "#/components/schemas/OpenApiChannelStats" }, "createdBy": { "$ref": "#/components/schemas/OpenApiUserBase" }, "createdAt": { "type": "string", "description": "The date the channel was created", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "updatedAt": { "type": "string", "description": "The most recent date the channel was updated", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" } }, "additionalProperties": false }, "OpenApiChannelBase": { "type": "object", "properties": { "channelId": { "type": "integer", "description": "The channel ID", "format": "int64", "nullable": true, "example": 1254 }, "name": { "type": "string", "description": "The channel name", "nullable": true, "example": "Ambassadors" }, "theme": { "$ref": "#/components/schemas/OpenApiChannelTheme" } }, "additionalProperties": false }, "OpenApiChannelOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiChannel" } }, "additionalProperties": false }, "OpenApiChannelPaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiChannel" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiChannelPaginatedResultOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiChannelPaginatedResult" } }, "additionalProperties": false }, "OpenApiChannelPostRequest": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "emoji": { "$ref": "#/components/schemas/Emoji" }, "image": { "$ref": "#/components/schemas/PostRequestImageObject" }, "icon": { "$ref": "#/components/schemas/ImageIcon" }, "backgroundColor": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "status": { "$ref": "#/components/schemas/ChannelStatus" }, "postAuthorType": { "$ref": "#/components/schemas/ChannelPostAuthorType" } }, "additionalProperties": false }, "OpenApiChannelProgram": { "type": "object", "properties": { "programId": { "type": "integer", "description": "The program ID", "format": "int32", "example": 1254 }, "name": { "type": "string", "description": "The program name", "nullable": true, "example": "Ambassadors" }, "key": { "type": "string", "description": "The program unique identifier when integrating with 3rd party data", "nullable": true, "example": "roster-ambassadors" }, "ambassadorsCount": { "type": "integer", "description": "The count of program members in the program", "format": "int32", "example": 1254 }, "participantsCount": { "type": "integer", "description": "The count of program members that participate in channel", "format": "int32", "example": 1254 } }, "additionalProperties": false }, "OpenApiChannelStats": { "type": "object", "properties": { "participantsCount": { "type": "integer", "description": "The channel participants count", "format": "int32", "example": 45 }, "commentsCount": { "type": "integer", "description": "The count of comments from published and archived posts", "format": "int32", "example": 45 }, "postsCount": { "type": "integer", "description": "The count of published and archived posts", "format": "int32", "example": 45 }, "latestActivity": { "type": "string", "description": "The date of most recent post or comment", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" } }, "additionalProperties": false }, "OpenApiChannelTheme": { "type": "object", "properties": { "emoji": { "$ref": "#/components/schemas/Emoji" }, "icon": { "$ref": "#/components/schemas/ImageIcon" }, "backgroundColor": { "type": "string", "nullable": true }, "image": { "$ref": "#/components/schemas/OpenApiImage" } }, "additionalProperties": false }, "OpenApiClick": { "type": "object", "properties": { "clickId": { "type": "integer", "description": "The click's system generated unique ID", "format": "int64", "example": 123456 }, "ambassador": { "$ref": "#/components/schemas/OpenApiContactBase" }, "referralLinkId": { "type": "string", "description": "The ambassador's referral ID", "nullable": true, "example": "HERO25" }, "createdAt": { "type": "string", "description": "The date and time the link click was captured", "format": "date-time", "example": "2022-10-31T11:59:00" }, "rcid": { "type": "string", "description": "The Roster Click ID for end-to-end attribution", "nullable": true, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "channel": { "type": "string", "description": "The platform/channel the user was on when they clicked (e.g., Instagram, Facebook, TikTok, Direct / Unknown). Fused from both redirect-service and pixel signals.", "nullable": true, "example": "Instagram" }, "channelSources": { "type": "string", "description": "The signals used to detect the channel (e.g., \"User Agent + Referrer (instagram.com)\")", "nullable": true, "example": "User Agent + Referrer (instagram.com)" }, "isPaidTraffic": { "type": "boolean", "description": "Whether the click originated from a paid ad (detected via gclid, fbclid, etc.). Null when the redirect service was bypassed and paid status cannot be determined.", "nullable": true, "example": true }, "paidTrafficSource": { "type": "string", "description": "The detected paid traffic source platform (e.g., google, facebook, tiktok)", "nullable": true, "example": "facebook" }, "referrer": { "$ref": "#/components/schemas/OpenApiClickReferrer" }, "landingPage": { "$ref": "#/components/schemas/OpenApiClickLandingPage" }, "landingPageUrl": { "type": "string", "description": "(Deprecated) The page URL where the pixel captured the click. Use `landingPage.landingPageUrl` instead.", "nullable": true, "example": "`https://example.com`", "deprecated": true }, "referrerUrl": { "type": "string", "description": "(Deprecated) The pixel-side referrer URL (often the brand's own domain after intermediate redirects). Use `referrer.referrerUrl` (with `referrer.referrerSource == \"pixel\"`) instead.", "nullable": true, "example": "`https://example.com`", "deprecated": true }, "utmParams": { "type": "string", "description": "(Deprecated) A JSON object of all UTM params extracted from the landing page URL by the pixel. Use `landingPage.queryParams` (then parse `utm_*` keys) or `referrer.queryParams` instead.", "nullable": true, "example": "`{\"utm_source\":\"instagram\"}`", "deprecated": true }, "queryParams": { "type": "string", "description": "(Deprecated) A JSON object of all URL params from the landing page URL as captured by the pixel. Use `landingPage.queryParams` instead.", "nullable": true, "example": "`{\"rstr\":\"HERO25\"}`", "deprecated": true }, "userAgent": { "type": "string", "description": "(Deprecated) The HTTP User Agent. Source is ambiguous — prefers the server-side smart-link user agent and falls back to the pixel-side user agent. Use `referrer.userAgent` or `landingPage.userAgent` instead.", "nullable": true, "example": "Mozilla/5.0 () () ", "deprecated": true }, "queryString": { "type": "string", "description": "(Deprecated) The inbound query string from the smart link redirect request. Use `referrer.queryParams` (when `referrer.referrerSource == \"redirect\"`) instead.", "nullable": true, "example": "fbclid=abc123&utm_source=instagram", "deprecated": true } }, "additionalProperties": false }, "OpenApiClickLandingPage": { "type": "object", "properties": { "landingPageUrl": { "type": "string", "description": "The page URL where the pixel captured the click.", "nullable": true, "example": "https://example.com/products/widget" }, "userAgent": { "type": "string", "description": "The HTTP User Agent of the browser running the tracking pixel.", "nullable": true, "example": "Mozilla/5.0 () () " }, "queryParams": { "type": "string", "description": "The query string (key=value&key=value form) of the landing-page URL, reconstructed from the pixel's queryParams payload.", "nullable": true, "example": "rstr=HERO25&utm_source=instagram" } }, "additionalProperties": false, "description": "Information about the brand-site page where the tracking pixel fired. Always populated from the pixel." }, "OpenApiClickListOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiClick" }, "description": "The response object", "nullable": true, "example": null } }, "additionalProperties": false }, "OpenApiClickReferrer": { "type": "object", "properties": { "referrerUrl": { "type": "string", "description": "The referrer URL. When `referrerSource` is \"redirect\", this is the HTTP Referer header captured server-side at the smart link redirect (often the originating platform, e.g. instagram.com). When \"pixel\", this is `document.referrer` from the pixel-side environment (often the brand's own domain after intermediate redirects).", "nullable": true, "example": "https://l.instagram.com/" }, "userAgent": { "type": "string", "description": "The HTTP User Agent of the request. From the smart link redirect when `referrerSource` is \"redirect\", from the browser running the tracking pixel when \"pixel\".", "nullable": true, "example": "Mozilla/5.0 () () " }, "queryParams": { "type": "string", "description": "The query string (key=value&key=value form) associated with the referring request. When `referrerSource` is \"redirect\", this is the inbound query string at the smart link redirect — useful for paid-traffic detection (gclid/fbclid/ttclid). When \"pixel\", reconstructed from the pixel's queryParams payload.", "nullable": true, "example": "fbclid=abc123&utm_source=instagram" }, "referrerSource": { "type": "string", "description": "Which side of the data flow provided this referrer information. \"redirect\" when a fresh SmartLinkLog row was matched at write time, \"pixel\" when the redirect service was bypassed and the pixel was the only signal.", "nullable": true, "example": "redirect" } }, "additionalProperties": false, "description": "Information about where the user came from before landing on the brand's site. Populated from the redirect service when a matching SmartLinkLog row exists, otherwise from the tracking pixel." }, "OpenApiComment": { "type": "object", "properties": { "commentId": { "type": "integer", "description": "The comment ID", "format": "int64", "example": 1254 }, "parentId": { "type": "integer", "description": "The ID of the comment's parent", "format": "int64", "example": 1254 }, "parentType": { "$ref": "#/components/schemas/ParentType" }, "message": { "type": "string", "description": "The comment message", "nullable": true, "example": "Wow this is great!" }, "author": { "$ref": "#/components/schemas/OpenApiAuthor" }, "commentsCount": { "type": "integer", "format": "int32" }, "likes": { "$ref": "#/components/schemas/OpenApiCommentLikes" }, "createdAt": { "type": "string", "description": "The date the comment was created", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "updatedAt": { "type": "string", "description": "The most recent date the comment was updated", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" } }, "additionalProperties": false }, "OpenApiCommentLikes": { "type": "object", "properties": { "likedByMe": { "$ref": "#/components/schemas/OpenApiLike" }, "count": { "type": "integer", "description": "The total count of likes", "format": "int32" } }, "additionalProperties": false }, "OpenApiCommentOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiComment" } }, "additionalProperties": false }, "OpenApiCommentPaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiComment" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiCommentPaginatedResultOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiCommentPaginatedResult" } }, "additionalProperties": false }, "OpenApiCommunityProfile": { "type": "object", "properties": { "slug": { "type": "string", "description": "The profile slug", "nullable": true, "example": "1234-abcd-5678" }, "userType": { "$ref": "#/components/schemas/OpenApiUserType" }, "profileImage": { "$ref": "#/components/schemas/OpenApiCommunityProfileImage" }, "bio": { "maxLength": 150, "type": "string", "description": "Bio", "nullable": true, "example": "I love to explore the great outdoors and share my experiences with others." }, "displayName": { "maxLength": 30, "type": "string", "description": "The profile display name", "nullable": true, "example": "John Doe" } }, "additionalProperties": false }, "OpenApiCommunityProfileImage": { "type": "object", "properties": { "imageUrl": { "type": "string", "description": "The profile image URL", "nullable": true, "example": "https://example.com/profile.jpg" }, "displayText": { "type": "string", "description": "The first two applicable characters in the display name.", "nullable": true, "example": "TE" }, "textColor": { "type": "string", "description": "The hex code color value of the display text.", "nullable": true, "example": "#000000" }, "backgroundColor": { "type": "string", "description": "The hex code color value of the profile image background.", "nullable": true, "example": "#FFFFFF" } }, "additionalProperties": false }, "OpenApiCommunityProfileOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiCommunityProfile" } }, "additionalProperties": false }, "OpenApiContact": { "type": "object", "properties": { "contactId": { "type": "integer", "description": "The contact's system generated unique ID", "format": "int64", "nullable": true, "example": 123456 }, "firstName": { "type": "string", "description": "The contact's first name", "nullable": true, "example": "Frodo" }, "lastName": { "type": "string", "description": "The contact's last name", "nullable": true, "example": "Baggins" }, "emailAddress": { "type": "string", "description": "The contact's email address", "nullable": true, "example": "example@email.com" }, "phoneNumber": { "type": "string", "description": "The contact's phone number", "nullable": true, "example": "+1-541-754-3010" }, "dateOfBirth": { "type": "string", "description": "The contact's birth date", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "shippingAddress": { "$ref": "#/components/schemas/OpenApiAddress" }, "program": { "$ref": "#/components/schemas/OpenApiContactProgram" }, "instagramHandles": { "type": "string", "description": "The contact's Instagram handles (comma-separated)", "nullable": true, "example": "first_ig,second_ig" }, "facebookHandles": { "type": "string", "description": "The contact's Facebook handles (comma-separated)", "nullable": true, "example": "first_fb,second_fb" }, "tiktokHandles": { "type": "string", "description": "The contact's TikTok handles (comma-separated)", "nullable": true, "example": "first_tt,second_tt" }, "twitterHandles": { "type": "string", "description": "The contact's Twitter handles (comma-separated)", "nullable": true, "example": "first_tt,second_tt" }, "tags": { "type": "string", "description": "The contact's tags (comma-separated)", "nullable": true, "example": "first_tt,second_tt" }, "sharableCodes": { "type": "string", "description": "The contact's sharable codes (comma-separated)", "nullable": true, "example": "sharable_code_1,sharable_code_2" }, "referralLink": { "type": "string", "description": "The contact's referral link", "nullable": true, "example": "https://myshop.myshopify.com/?rstr=12345" }, "referralLinkIds": { "type": "string", "description": "The contact's referral link ids (comma-separated, newest first)", "nullable": true, "example": "link_id_1,link_id_2" }, "contactOwnerEmail": { "type": "string", "description": "The contact's owner email", "nullable": true, "example": "example@email.com" }, "lifeTimePoints": { "type": "number", "description": "The contact's earned points", "format": "double", "nullable": true, "example": 37 }, "magicCode": { "type": "string", "description": "The contact's magic code", "nullable": true, "example": "645n-3gah-jzse" }, "dateAdded": { "type": "string", "description": "The date contact added to the system", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "termsAgreementDate": { "type": "string", "format": "date-time", "nullable": true }, "lastAccessedPortalDate": { "type": "string", "description": "The date contact last logged in to the system", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" } }, "additionalProperties": false }, "OpenApiContactBase": { "type": "object", "properties": { "contactId": { "type": "integer", "description": "The contact's system generated unique ID", "format": "int64", "nullable": true, "example": 123456 }, "firstName": { "type": "string", "description": "The contact's first name", "nullable": true, "example": "Frodo" }, "lastName": { "type": "string", "description": "The contact's last name", "nullable": true, "example": "Baggins" }, "emailAddress": { "type": "string", "description": "The contact's email address", "nullable": true, "example": "example@email.com" } }, "additionalProperties": false }, "OpenApiContactCommissions": { "type": "object", "properties": { "pending": { "type": "number", "format": "double" }, "approved": { "type": "number", "format": "double" }, "paid": { "type": "number", "format": "double" }, "lastPaidAt": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false }, "OpenApiContactLastActivity": { "type": "object", "properties": { "lastPortalLoginAt": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false }, "OpenApiContactOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiContact" } }, "additionalProperties": false }, "OpenApiContactPerformanceResponse": { "type": "object", "properties": { "contactId": { "type": "integer", "format": "int64" }, "referral": { "$ref": "#/components/schemas/OpenApiContactReferralPerformance" }, "personalOrders": { "$ref": "#/components/schemas/OpenApiContactPersonalOrders" }, "commissions": { "$ref": "#/components/schemas/OpenApiContactCommissions" }, "social": { "$ref": "#/components/schemas/OpenApiContactSocialPerformance" }, "lastActivity": { "$ref": "#/components/schemas/OpenApiContactLastActivity" } }, "additionalProperties": false }, "OpenApiContactPerformanceResponseOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiContactPerformanceResponse" } }, "additionalProperties": false }, "OpenApiContactPersonalOrders": { "type": "object", "properties": { "count": { "type": "integer", "format": "int32" }, "totalSpent": { "type": "number", "format": "double" } }, "additionalProperties": false }, "OpenApiContactPostRequest": { "required": [ "email", "firstName" ], "type": "object", "properties": { "phoneNumber": { "type": "string", "description": "The phone of the new contact", "format": "tel", "nullable": true, "example": "+1-541-754-3010" }, "lastName": { "type": "string", "description": "The last name of the new contact", "nullable": true, "example": "Baggins" }, "dateOfBirth": { "type": "string", "description": "The contact's birth date", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "instagramHandles": { "type": "string", "description": "The contact's Instagram handles (comma-separated)", "nullable": true, "example": "first_ig,second_ig" }, "facebookHandles": { "type": "string", "description": "The contact's Facebook handles (comma-separated)", "nullable": true, "example": "first_fb,second_fb" }, "tiktokHandles": { "type": "string", "description": "The contact's TikTok handles (comma-separated)", "nullable": true, "example": "first_tt,second_tt" }, "twitterHandles": { "type": "string", "description": "The contact's Twitter handles (comma-separated)", "nullable": true, "example": "first_tt,second_tt" }, "shippingAddress": { "$ref": "#/components/schemas/OpenApiAddress" }, "referralLinkId": { "type": "string", "description": "The contact's referral link ids (comma-separated, newest first)", "nullable": true, "example": "sharable_code_1" }, "contactOwnerEmail": { "type": "string", "description": "The contact's owner email", "nullable": true, "example": "example@email.com" }, "addTags": { "type": "string", "description": "Tag(s) to add to the contact (comma-separated; case will be preserved)", "nullable": true, "example": "tag0,tag1" }, "email": { "minLength": 1, "type": "string", "description": "The email of the new contact", "format": "email", "example": "example@email.com" }, "firstName": { "minLength": 1, "type": "string", "description": "The first name of the new contact", "example": "Frodo" } }, "additionalProperties": false }, "OpenApiContactProgram": { "type": "object", "properties": { "programId": { "type": "integer", "description": "The program ID", "format": "int64", "example": 123456 }, "programName": { "type": "string", "description": "The name of program", "nullable": true, "example": "Ambassadors" }, "programKey": { "type": "string", "description": "The key of program", "nullable": true, "example": "ambassadors-123456" }, "dateAdded": { "type": "string", "description": "The date the customer added to program", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" } }, "additionalProperties": false }, "OpenApiContactProgramBase": { "type": "object", "properties": { "contactId": { "type": "integer", "description": "The contact's system generated unique ID", "format": "int64", "nullable": true, "example": 123456 }, "firstName": { "type": "string", "description": "The contact's first name", "nullable": true, "example": "Frodo" }, "lastName": { "type": "string", "description": "The contact's last name", "nullable": true, "example": "Baggins" }, "emailAddress": { "type": "string", "description": "The contact's email address", "nullable": true, "example": "example@email.com" }, "programId": { "type": "integer", "description": "The ambassador's program ID", "format": "int64", "nullable": true, "example": 12 } }, "additionalProperties": false }, "OpenApiContactProperty": { "type": "object", "properties": { "contactId": { "type": "integer", "description": "The contact's system generated unique ID", "format": "int64", "nullable": true, "example": 123456 }, "propertyId": { "type": "integer", "description": "The property's system generated unique ID", "format": "int64", "nullable": true, "example": 7890 }, "propertyName": { "type": "string", "description": "The name of the property", "nullable": true, "example": "Age" }, "propertySlug": { "type": "string", "description": "The slug identifier for the property (format: label-slug-xxxx). Used for CSV column mapping as \"Custom: {slug}\"", "nullable": true, "example": "shirt-size-a1b2" }, "propertyValue": { "description": "The value of the property", "nullable": true, "example": 21 }, "createdAt": { "type": "string", "description": "The date the property was created", "format": "date-time", "example": "2022-10-31T11:59:00" }, "updatedAt": { "type": "string", "description": "The date the property code was modified", "format": "date-time", "example": "2022-10-31T11:59:00" } }, "additionalProperties": false }, "OpenApiContactPropertyOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiContactProperty" } }, "additionalProperties": false }, "OpenApiContactPropertyPostRequest": { "required": [ "propertyId", "propertyValue" ], "type": "object", "properties": { "propertyValue": { "description": "The property's value", "example": 12345 }, "propertyId": { "type": "integer", "description": "The property's system generated unique ID", "format": "int64", "example": 12345 } }, "additionalProperties": false }, "OpenApiContactPropertyPutRequest": { "required": [ "propertyValue" ], "type": "object", "properties": { "propertyValue": { "description": "The property's value", "example": 12345 } }, "additionalProperties": false }, "OpenApiContactPutRequest": { "required": [ "contactId" ], "type": "object", "properties": { "phoneNumber": { "type": "string", "description": "The phone of the new contact", "format": "tel", "nullable": true, "example": "+1-541-754-3010" }, "lastName": { "type": "string", "description": "The last name of the new contact", "nullable": true, "example": "Baggins" }, "dateOfBirth": { "type": "string", "description": "The contact's birth date", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "instagramHandles": { "type": "string", "description": "The contact's Instagram handles (comma-separated)", "nullable": true, "example": "first_ig,second_ig" }, "facebookHandles": { "type": "string", "description": "The contact's Facebook handles (comma-separated)", "nullable": true, "example": "first_fb,second_fb" }, "tiktokHandles": { "type": "string", "description": "The contact's TikTok handles (comma-separated)", "nullable": true, "example": "first_tt,second_tt" }, "twitterHandles": { "type": "string", "description": "The contact's Twitter handles (comma-separated)", "nullable": true, "example": "first_tt,second_tt" }, "shippingAddress": { "$ref": "#/components/schemas/OpenApiAddress" }, "referralLinkId": { "type": "string", "description": "The contact's referral link ids (comma-separated, newest first)", "nullable": true, "example": "sharable_code_1" }, "contactOwnerEmail": { "type": "string", "description": "The contact's owner email", "nullable": true, "example": "example@email.com" }, "addTags": { "type": "string", "description": "Tag(s) to add to the contact (comma-separated; case will be preserved)", "nullable": true, "example": "tag0,tag1" }, "contactId": { "type": "integer", "description": "The list of contact's system generated unique ID to filter by", "format": "int64", "example": 12345 }, "email": { "type": "string", "description": "The email of the new contact", "format": "email", "nullable": true, "example": "example@email.com" }, "firstName": { "type": "string", "description": "The first name of the new contact", "nullable": true, "example": "Frodo" }, "removeTags": { "type": "string", "description": "Tag(s) to remove from the contact (comma-separated; case-insensitive)", "nullable": true, "example": "tag0,tag1" } }, "additionalProperties": false }, "OpenApiContactReferralPerformance": { "type": "object", "properties": { "lifetimeRevenue": { "type": "number", "format": "double" }, "lifetimeOrders": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "OpenApiContactSearchRow": { "type": "object", "properties": { "contactId": { "type": "integer", "format": "int64" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "socials": { "type": "array", "items": { "$ref": "#/components/schemas/AccountSocialProfile" }, "nullable": true }, "tags": { "type": "array", "items": { }, "nullable": true }, "customProperties": { "type": "array", "items": { "type": "string" }, "nullable": true }, "programs": { "type": "array", "items": { "$ref": "#/components/schemas/AccountProgram" }, "nullable": true }, "lifetimeReferralRevenue": { "type": "number", "format": "double" }, "lifetimeReferralOrders": { "type": "integer", "format": "int32" }, "lastReferralAt": { "type": "string", "format": "date-time", "nullable": true }, "postMentionsTotal": { "type": "integer", "format": "int64" }, "lastMentionAt": { "type": "string", "format": "date-time", "nullable": true }, "totalSpent": { "type": "number", "format": "double" }, "ordersCount": { "type": "integer", "format": "int32" }, "totalFollowers": { "type": "integer", "format": "int64" }, "averageEngagement": { "type": "number", "format": "double" }, "totalPoints": { "type": "number", "format": "double", "nullable": true }, "lastPortalLoginAt": { "type": "string", "format": "date-time", "nullable": true }, "referralLinkIds": { "type": "array", "items": { "$ref": "#/components/schemas/AccountReferralLinkId" }, "nullable": true }, "discountCodes": { "type": "array", "items": { "$ref": "#/components/schemas/DiscountCode" }, "nullable": true }, "joinedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "OpenApiContactSearchRowPaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiContactSearchRow" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiContactSearchSortField": { "enum": [ "referralRevenue", "posts", "joinedDate", "followers", "engagement", "totalSpent" ], "type": "string" }, "OpenApiContactSocialPerformance": { "type": "object", "properties": { "posts": { "type": "integer", "format": "int32" }, "stories": { "type": "integer", "format": "int32" }, "reach": { "type": "number", "format": "double" }, "impressions": { "type": "integer", "format": "int32" }, "engagement": { "type": "number", "format": "double" }, "emv": { "type": "number", "format": "double" } }, "additionalProperties": false }, "OpenApiCreateClickParams": { "type": "object", "properties": { "referralLinkId": { "type": "string", "description": "The referral identifier from the referral link (e.g. in the referral link `https://example.com/?rstr=123abc`, the referral ID is `123abc`", "nullable": true, "example": "123abc" }, "landingPageUrl": { "type": "string", "description": "The current page where the click was captured", "nullable": true, "example": "https://example.com" }, "referrerUrl": { "type": "string", "description": "The http referrer", "nullable": true, "example": "`https://example.com`" }, "utmParams": { "description": "A JSON object of all UTM params from landing page URL", "nullable": true }, "queryParams": { "description": "A JSON object of all URL params from the landing page URL", "nullable": true }, "userAgent": { "type": "string", "description": "The HTTP User Agent", "nullable": true, "example": "Mozilla/5.0 () () " } }, "additionalProperties": false }, "OpenApiCustomProperty": { "type": "object", "properties": { "propertyId": { "type": "integer", "description": "The ID for the property", "format": "int64", "example": 1254 }, "value": { "description": "The data entry provided by the ambassador when filling out the application form. Can be a dynamic json object or string.", "nullable": true }, "valueString": { "type": "string", "description": "The string representation of the `value` object.", "nullable": true } }, "additionalProperties": false }, "OpenApiCustomer": { "type": "object", "properties": { "customerId": { "type": "integer", "description": "The customer's system generated unique ID", "format": "int64", "nullable": true, "example": 123456 }, "externalCustomerId": { "type": "string", "description": "The external system's unique ID for the customer", "nullable": true, "example": "1k384s78323b" }, "firstName": { "type": "string", "description": "The customer's first name", "nullable": true, "example": "Diana" }, "lastName": { "type": "string", "description": "The customer's last name", "nullable": true, "example": "Prince" }, "emailAddress": { "type": "string", "description": "The customer's email address", "nullable": true, "example": "example@email.com" }, "ordersCount": { "type": "integer", "description": "The total count of orders for this customer based on the data we have in our system", "format": "int32", "nullable": true, "example": 3 } }, "additionalProperties": false }, "OpenApiDiscountCode": { "type": "object", "properties": { "id": { "type": "integer", "description": "The discount code ID", "format": "int64", "example": 123456 }, "discountRuleId": { "type": "integer", "description": "The discount rule ID associated with the discount code", "format": "int64", "example": 123456 }, "ruleType": { "$ref": "#/components/schemas/RuleTypes" }, "code": { "type": "string", "description": "The discount code", "nullable": true, "example": "abc_CODE" }, "ambassador": { "$ref": "#/components/schemas/OpenApiContactBase" }, "status": { "$ref": "#/components/schemas/DiscounCodeStatus" }, "uses": { "type": "integer", "description": "The amount of discount code uses", "format": "int32", "example": 11 }, "revenue": { "type": "number", "description": "The revenue from discount code uses", "format": "double", "example": 1111.11 }, "createdAt": { "type": "string", "description": "The date the discount code was created", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The date the discount code was modified", "format": "date-time" } }, "additionalProperties": false }, "OpenApiDiscountCodePaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiDiscountCode" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiDiscountRule": { "type": "object", "properties": { "id": { "type": "integer", "description": "The discount rule ID", "format": "int64", "example": 123456 }, "externalSourceId": { "type": "string", "description": "The external discount rule ID", "nullable": true, "example": "123456789" }, "title": { "type": "string", "description": "The discount rule title", "nullable": true, "example": "Summer Sale" }, "description": { "type": "string", "description": "The discount rule Description", "nullable": true, "example": "Buy one, get nothing" }, "ruleType": { "$ref": "#/components/schemas/RuleTypes" }, "status": { "$ref": "#/components/schemas/RuleStatus" }, "discountType": { "$ref": "#/components/schemas/DiscountTypes" }, "discountAmount": { "type": "number", "description": "The amount of discount rule discount", "format": "double", "nullable": true, "example": 50 }, "appliesToCollectionIds": { "type": "array", "items": { "type": "string" }, "description": "The list of Collection Ids discount rule applies to", "nullable": true, "example": [ "12345", "54321" ] }, "appliesToProductIds": { "type": "array", "items": { "type": "string" }, "description": "The list of Product Ids discount rule applies to", "nullable": true, "example": [ "12345", "54321" ] }, "appliesToVariantIds": { "type": "array", "items": { "type": "string" }, "description": "The list of Variant Ids discount rule applies to", "nullable": true, "example": [ "12345", "54321" ] }, "usageLimitPerCode": { "type": "integer", "description": "The discount code usage limit", "format": "int64", "example": 10 }, "limitOnePerCustomer": { "type": "boolean", "description": "Limit to one code per customer" }, "programs": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedObject" }, "description": "The list of programs where discount rule is used", "nullable": true }, "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedObject" }, "description": "The list of campaigns where discount rule is used", "nullable": true }, "milestoneSeries": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedObject" }, "description": "The list of milestone series where discount rule is used", "nullable": true }, "startDate": { "type": "string", "description": "The start date discount rule", "format": "date-time" }, "endDate": { "type": "string", "description": "The amount of unassigned discount code", "format": "date-time", "nullable": true }, "assigned": { "type": "integer", "description": "The amount of assigned discount code in discount rule", "format": "int64", "example": 11 }, "unassigned": { "type": "integer", "description": "The amount of unassigned discount code in discount rule", "format": "int64", "example": 11 }, "uses": { "type": "integer", "description": "The amount of discount code uses in discount rule", "format": "int32", "example": 11 }, "revenue": { "type": "number", "description": "The revenue from discount code uses in discount rule", "format": "double", "example": 1111.11 }, "createdAt": { "type": "string", "description": "The date the discount code was modified", "format": "date-time" }, "prefix": { "type": "string", "description": "Prefix to apply to discount codes", "nullable": true }, "updatedAt": { "type": "string", "description": "The date the discount code was modified", "format": "date-time" }, "isArchived": { "type": "boolean", "description": "Whether the discount rule has been archived" } }, "additionalProperties": false }, "OpenApiDiscountRulePaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiDiscountRule" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiEvent": { "type": "object", "properties": { "eventId": { "type": "integer", "description": "The event's system generated unique ID", "format": "int64", "example": 123456 }, "arguments": { "description": "The Event-specific JSON object relevant to the event and its resources.", "nullable": true }, "path": { "type": "string", "description": "A relative URL to the resource the event is for, if applicable.", "nullable": true, "example": "`https://app.getroster.com/rewards/723`" }, "message": { "type": "string", "description": "A human readable description of the event.", "nullable": true, "example": "New automated product reward redeemed." }, "subjectId": { "type": "integer", "description": "The ID of the resource that generated the event.", "format": "int64", "example": 723 }, "subjectType": { "$ref": "#/components/schemas/EventSubjectType" }, "verb": { "$ref": "#/components/schemas/EventVerbType" }, "createdAt": { "type": "string", "description": "The date and time the link click was captured", "format": "date-time", "example": "2022-10-31T11:59:00" }, "updatedAt": { "type": "string", "description": "The date and time the link click was captured", "format": "date-time", "example": "2022-10-31T11:59:00" } }, "additionalProperties": false }, "OpenApiEventOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiEvent" } }, "additionalProperties": false }, "OpenApiEventPaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiEvent" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiImage": { "type": "object", "properties": { "fileName": { "type": "string", "description": "The file name of the image", "nullable": true, "example": "image.jpg" }, "fileUrl": { "type": "string", "description": "The source url of the image", "nullable": true, "example": "https://www.example.com/image.jpg" }, "resourceId": { "type": "integer", "description": "The resource linked to the image", "format": "int32", "nullable": true, "example": 1234 } }, "additionalProperties": false }, "OpenApiLike": { "type": "object", "properties": { "likeId": { "type": "integer", "description": "The like ID", "format": "int64", "example": 1254 }, "parentId": { "type": "integer", "description": "The ID of the like's parent", "format": "int64", "example": 1254 }, "parentType": { "$ref": "#/components/schemas/ParentType" }, "user": { "$ref": "#/components/schemas/OpenApiAuthor" }, "createdAt": { "type": "string", "description": "The date the like was created", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "updatedAt": { "type": "string", "description": "The most recent date the like was updated", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" } }, "additionalProperties": false }, "OpenApiLikeOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiLike" } }, "additionalProperties": false }, "OpenApiLikePaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiLike" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiLikePaginatedResultOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiLikePaginatedResult" } }, "additionalProperties": false }, "OpenApiLikes": { "type": "object", "properties": { "firstLikes": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiLike" }, "description": "First likes", "nullable": true }, "count": { "type": "integer", "description": "The total count of likes", "format": "int32" }, "likedByMe": { "$ref": "#/components/schemas/OpenApiLike" } }, "additionalProperties": false }, "OpenApiLinkClick": { "type": "object", "properties": { "rcid": { "type": "string", "description": "The Roster Click ID for end-to-end attribution", "nullable": true, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "referrer": { "type": "string", "description": "The HTTP Referer from the originating platform (e.g., Instagram, TikTok). Captured server-side at the smart link redirect.", "nullable": true, "example": "https://l.instagram.com/" }, "userAgent": { "type": "string", "description": "The HTTP User Agent at the time of the click", "nullable": true, "example": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X)" }, "queryString": { "type": "string", "description": "The inbound query string from the smart link redirect request", "nullable": true, "example": "fbclid=abc123&utm_source=instagram" }, "isPaidTraffic": { "type": "boolean", "description": "Whether the click originated from a paid ad (detected via gclid, fbclid, etc.)", "nullable": true, "example": true }, "paidTrafficSource": { "type": "string", "description": "The detected paid traffic source platform (e.g., google, facebook, tiktok)", "nullable": true, "example": "facebook" }, "channel": { "type": "string", "description": "The platform/channel the user was on when they clicked (e.g., Instagram, Facebook, TikTok, Direct / Unknown)", "nullable": true, "example": "Instagram" }, "channelSources": { "type": "string", "description": "The signals used to detect the channel (e.g., \"User Agent + Referrer (instagram.com)\")", "nullable": true, "example": "User Agent + Referrer (instagram.com)" } }, "additionalProperties": false, "description": "The originating link click that led to this attribution, matched via Roster Click ID (rcid)" }, "OpenApiManualCashRewardPostRequest": { "type": "object", "properties": { "ambassadorId": { "type": "integer", "description": "The ambassador being paid", "format": "int64" }, "amount": { "type": "number", "description": "The cash amount, in the brand's configured currency. Must be greater than 0.", "format": "double" }, "internalNote": { "type": "string", "description": "Why this reward was given. A manual reward has no campaign or milestone to explain it,\r\nso without a note nobody can later tell why it was paid.", "nullable": true }, "ambassadorNote": { "type": "string", "description": "Optional note shown to the ambassador", "nullable": true } }, "additionalProperties": false }, "OpenApiMeResponse": { "type": "object", "properties": { "brandUserId": { "type": "integer", "format": "int64" }, "brandName": { "type": "string", "nullable": true }, "brandDomain": { "type": "string", "nullable": true }, "tokenCreatedAt": { "type": "string", "format": "date-time" }, "accessType": { "type": "string", "nullable": true } }, "additionalProperties": false }, "OpenApiMeResponseOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiMeResponse" } }, "additionalProperties": false }, "OpenApiMessage": { "required": [ "html", "json", "text" ], "type": "object", "properties": { "json": { "minLength": 1, "type": "string", "description": "Lexical JSON editor state" }, "html": { "minLength": 1, "type": "string", "description": "HTML representation of the message" }, "text": { "maxLength": 2000, "minLength": 0, "type": "string", "description": "Plain text representation of the message" } }, "additionalProperties": false }, "OpenApiMilestone": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "pointsNeeded": { "type": "number", "format": "double" } }, "additionalProperties": false }, "OpenApiMilestoneSeriesParticipant": { "type": "object", "properties": { "milestoneSeriesId": { "type": "integer", "description": "The Milestone Series ID", "format": "int64", "example": 123456 }, "participant": { "$ref": "#/components/schemas/OpenApiContactProgramBase" }, "currentMilestone": { "$ref": "#/components/schemas/OpenApiMilestone" }, "currentMilestoneDate": { "type": "string", "format": "date-time", "nullable": true }, "nextMilestone": { "$ref": "#/components/schemas/OpenApiMilestone" }, "currentPoints": { "type": "number", "format": "double" }, "lastPointsDate": { "type": "string", "format": "date-time", "nullable": true }, "iteration": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "OpenApiMilestoneSeriesParticipantPaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiMilestoneSeriesParticipant" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiMilestoneSeriesReward": { "type": "object", "properties": { "id": { "type": "integer", "description": "The reward ID", "format": "int64", "example": 123456 }, "ambassador": { "$ref": "#/components/schemas/OpenApiContactProgramBase" }, "type": { "$ref": "#/components/schemas/RewardType" }, "status": { "$ref": "#/components/schemas/RewardFulfillmentStatus" }, "rewardStatusId": { "type": "integer", "description": "The raw status id. Reward statuses come from two deliberately separate value spaces:\r\nfulfilment (601 Pending / 276 Fulfilled / 602 Won't fulfill / 894 Redeemed / 895 Not\r\nredeemed / 1258 Redemption failed) and money (530 Pending / 536 Approved / 537 Paid /\r\n538 Rejected). Cash rewards use the money ladder, so App.OpenApi.Domain.Models.Base.Engagement.Rewards.OpenApiRewardBase.Status cannot represent\r\nthem - branch on the reward type and read this instead.", "format": "int32", "example": 530 }, "cashAmount": { "type": "number", "description": "The cash value of this reward, or null when it is not a cash reward. Null is the\r\ndiscriminator: a points or product reward has no amount at all, which is different from an\r\namount of zero, and must never be rendered as money.", "format": "double", "nullable": true, "example": 50 }, "statusDate": { "type": "string", "description": "The date the status was modified", "format": "date-time", "nullable": true }, "rewardTemplate": { "$ref": "#/components/schemas/OpenApiRewardTemplate" }, "discountCode": { "$ref": "#/components/schemas/OpenApiRewardDiscountCode" }, "order": { "$ref": "#/components/schemas/OpenApiRewardOrder" }, "createdAt": { "type": "string", "description": "The timestamp the reward was created", "format": "date-time", "example": "2022-10-31T11:59:00" }, "updatedAt": { "type": "string", "description": "The most recent timestamp the reward was updated", "format": "date-time", "example": "2022-10-31T11:59:00" }, "milestoneSeriesId": { "type": "integer", "format": "int64" }, "iteration": { "type": "integer", "format": "int32" }, "milestone": { "$ref": "#/components/schemas/OpenApiRewardMilestone" }, "address": { "$ref": "#/components/schemas/OpenApiAddress" } }, "additionalProperties": false }, "OpenApiMilestoneSeriesRewardPaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiMilestoneSeriesReward" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiOrder": { "required": [ "currency", "externalOrderId", "externalOrderSource" ], "type": "object", "properties": { "orderId": { "type": "integer", "description": "The Roster order ID", "format": "int64", "nullable": true, "example": 123456 }, "orderDate": { "type": "string", "description": "The date the order was placed", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "subtotalPrice": { "type": "number", "description": "The order total after discounts but before taxes and shipping", "format": "double", "nullable": true, "example": 44.99 }, "totalPrice": { "type": "number", "description": "The order total after discounts and with taxes and shipping", "format": "double", "nullable": true, "example": 49.98 }, "externalOrderSource": { "$ref": "#/components/schemas/ExternalOrderSource" }, "externalOrderId": { "minLength": 1, "type": "string", "description": "The external order ID (e.g. the Shopify order ID)", "example": "209834573494" }, "externalOrderNumber": { "type": "string", "description": "The external system's order number", "nullable": true, "example": "84524" }, "financialStatus": { "$ref": "#/components/schemas/OrderFinancialStatus" }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "fulfillmentStatus": { "$ref": "#/components/schemas/OrderFulfillmentStatus" }, "discountCodes": { "type": "array", "items": { "type": "string" }, "description": "The list of discount codes applied to the order", "nullable": true, "example": [ "DISCOUNT25", "SUMMERSALE15" ] }, "referralLinkId": { "type": "string", "description": "The referral ID from the referring ambassador’s referral link", "nullable": true, "example": "mycustomid" }, "currency": { "minLength": 1, "type": "string", "description": "The currency of the order. (ISO 4217 - Alpha3)", "example": "USD" }, "externalOrderStatusUrl": { "type": "string", "description": "The URL that the customer can use to track their order status.", "nullable": true, "example": "https://mystore.myshopify.com/988715124/orders/co5t9f5ba34ae354b8f4h6a" }, "isNewCustomer": { "type": "boolean", "description": "Indicate whether or not this is a first-time customer", "nullable": true }, "cancelledAt": { "type": "string", "description": "The date the order was cancelled", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" } }, "additionalProperties": false }, "OpenApiOrderLineItem": { "required": [ "price", "productId", "quantity" ], "type": "object", "properties": { "productId": { "minLength": 1, "type": "string" }, "variantId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "quantity": { "type": "integer", "format": "int32" }, "price": { "type": "number", "format": "double" }, "discountedPrice": { "type": "number", "format": "double", "nullable": true }, "sku": { "type": "string", "nullable": true } }, "additionalProperties": false }, "OpenApiOrderOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiOrder" } }, "additionalProperties": false }, "OpenApiOrderPostCustomer": { "type": "object", "properties": { "externalCustomerId": { "type": "string", "description": "The external system's unique ID for the customer", "nullable": true, "example": "1k384s78323b" }, "firstName": { "type": "string", "description": "The customer's first name", "nullable": true, "example": "Diana" }, "lastName": { "type": "string", "description": "The customer's last name", "nullable": true, "example": "Prince" }, "emailAddress": { "type": "string", "description": "The customer's email address", "nullable": true, "example": "example@email.com" } }, "additionalProperties": false }, "OpenApiOrdersCaptureRequest": { "required": [ "externalOrderId" ], "type": "object", "properties": { "externalOrderId": { "minLength": 1, "type": "string", "description": "The external order ID (e.g. the Shopify order ID)", "example": "209834573494" }, "externalOrderNumber": { "type": "string", "description": "The external system's order number", "nullable": true, "example": "84524" }, "orderDate": { "type": "string", "description": "The date the order was placed", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "customer": { "$ref": "#/components/schemas/OpenApiOrderPostCustomer" }, "isNewCustomer": { "type": "boolean", "description": "Indicate whether or not this is a first-time customer", "nullable": true }, "discountCodes": { "type": "array", "items": { "type": "string" }, "description": "The list of discount codes applied to the order", "nullable": true, "example": [ "DISCOUNT25", "SUMMERSALE15" ] }, "referralLinkId": { "type": "string", "description": "The referral ID from the referring ambassador’s referral link", "nullable": true, "example": "mycustomid" }, "currency": { "type": "string", "description": "The currency of the order. (ISO 4217 - Alpha3)", "nullable": true, "example": "USD" }, "subtotalPrice": { "type": "number", "description": "The order total after discounts but before taxes and shipping (recommended)", "format": "double", "nullable": true, "example": 44.99 }, "totalPrice": { "type": "number", "description": "The order total after discounts and with taxes and shipping", "format": "double", "nullable": true, "example": 49.98 } }, "additionalProperties": false }, "OpenApiOrdersGetResponse": { "required": [ "currency", "externalOrderId", "externalOrderSource" ], "type": "object", "properties": { "orderId": { "type": "integer", "description": "The Roster order ID", "format": "int64", "nullable": true, "example": 123456 }, "orderDate": { "type": "string", "description": "The date the order was placed", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "subtotalPrice": { "type": "number", "description": "The order total after discounts but before taxes and shipping", "format": "double", "nullable": true, "example": 44.99 }, "totalPrice": { "type": "number", "description": "The order total after discounts and with taxes and shipping", "format": "double", "nullable": true, "example": 49.98 }, "externalOrderSource": { "$ref": "#/components/schemas/ExternalOrderSource" }, "externalOrderId": { "minLength": 1, "type": "string", "description": "The external order ID (e.g. the Shopify order ID)", "example": "209834573494" }, "externalOrderNumber": { "type": "string", "description": "The external system's order number", "nullable": true, "example": "84524" }, "financialStatus": { "$ref": "#/components/schemas/OrderFinancialStatus" }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "fulfillmentStatus": { "$ref": "#/components/schemas/OrderFulfillmentStatus" }, "discountCodes": { "type": "array", "items": { "type": "string" }, "description": "The list of discount codes applied to the order", "nullable": true, "example": [ "DISCOUNT25", "SUMMERSALE15" ] }, "referralLinkId": { "type": "string", "description": "The referral ID from the referring ambassador’s referral link", "nullable": true, "example": "mycustomid" }, "currency": { "minLength": 1, "type": "string", "description": "The currency of the order. (ISO 4217 - Alpha3)", "example": "USD" }, "externalOrderStatusUrl": { "type": "string", "description": "The URL that the customer can use to track their order status.", "nullable": true, "example": "https://mystore.myshopify.com/988715124/orders/co5t9f5ba34ae354b8f4h6a" }, "isNewCustomer": { "type": "boolean", "description": "Indicate whether or not this is a first-time customer", "nullable": true }, "cancelledAt": { "type": "string", "description": "The date the order was cancelled", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "customer": { "$ref": "#/components/schemas/OpenApiCustomer" }, "createdAt": { "type": "string", "description": "The date the order was created", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "updatedAt": { "type": "string", "description": "The most recent date the order was updated", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" } }, "additionalProperties": false }, "OpenApiOrdersGetResponseOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiOrdersGetResponse" } }, "additionalProperties": false }, "OpenApiOrdersGetResponsePaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiOrdersGetResponse" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiOrdersPostRequest": { "required": [ "currency", "externalOrderId", "orderDate", "totalPrice" ], "type": "object", "properties": { "externalOrderId": { "minLength": 1, "type": "string", "description": "The external order ID (e.g. the Shopify order ID)", "example": "209834573494" }, "externalOrderNumber": { "type": "string", "description": "The external system's order number", "nullable": true, "example": "84524" }, "orderDate": { "type": "string", "description": "The date the order was placed", "format": "date-time", "example": "2022-10-31T11:59:00" }, "customer": { "$ref": "#/components/schemas/OpenApiOrderPostCustomer" }, "isNewCustomer": { "type": "boolean", "description": "Indicate whether or not this is a first-time customer", "nullable": true }, "discountCodes": { "type": "array", "items": { "type": "string" }, "description": "The list of discount codes applied to the order", "nullable": true, "example": [ "DISCOUNT25", "SUMMERSALE15" ] }, "referralLinkId": { "type": "string", "description": "The referral ID from the referring ambassador’s referral link", "nullable": true, "example": "mycustomid" }, "currency": { "minLength": 1, "type": "string", "description": "The currency of the order. (ISO 4217 - Alpha3)", "example": "USD" }, "subtotalPrice": { "type": "number", "description": "The order total after discounts but before taxes and shipping", "format": "double", "nullable": true, "example": 44.99 }, "totalPrice": { "type": "number", "description": "The order total after discounts and with taxes and shipping", "format": "double", "example": 49.98 }, "financialStatus": { "$ref": "#/components/schemas/OrderFinancialStatus" }, "fulfillmentStatus": { "$ref": "#/components/schemas/OrderFulfillmentStatus" }, "externalOrderStatusUrl": { "type": "string", "description": "The URL that the customer can use to track their order status.", "nullable": true, "example": "https://mystore.myshopify.com/988715124/orders/co5t9f5ba34ae354b8f4h6a" }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiOrderLineItem" }, "description": "Optional line items for per-product commission calculation", "nullable": true } }, "additionalProperties": false }, "OpenApiOrdersPutRequest": { "required": [ "totalPrice" ], "type": "object", "properties": { "externalOrderId": { "type": "string", "description": "The external order ID (e.g. the Shopify order ID)", "nullable": true, "example": "209834573494" }, "externalOrderNumber": { "type": "string", "description": "The external system's order number", "nullable": true, "example": "84524" }, "currency": { "type": "string", "description": "The currency of the order. (ISO 4217 - Alpha3)", "nullable": true, "example": "USD" }, "subtotalPrice": { "type": "number", "description": "The order total after discounts but before taxes and shipping", "format": "double", "nullable": true, "example": 44.99 }, "totalPrice": { "type": "number", "description": "The order total after discounts and with taxes and shipping", "format": "double", "example": 49.98 }, "financialStatus": { "$ref": "#/components/schemas/OrderFinancialStatus" }, "fulfillmentStatus": { "$ref": "#/components/schemas/OrderFulfillmentStatus" }, "externalOrderStatusUrl": { "type": "string", "description": "The URL that the customer can use to track their order status.", "nullable": true, "example": "https://mystore.myshopify.com/988715124/orders/co5t9f5ba34ae354b8f4h6a" }, "cancelledAt": { "type": "string", "description": "The date the order was cancelled. The cancelation date can't be in future.", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiOrderLineItem" }, "description": "Optional line items for per-product commission calculation", "nullable": true } }, "additionalProperties": false }, "OpenApiParticipantPostStats": { "type": "object", "properties": { "totalLikes": { "type": "integer", "description": "Total number of likes on the campaign participant's posts", "format": "int64", "example": 854 }, "totalComments": { "type": "integer", "description": "Total number of comments on the campaign participant's posts", "format": "int64", "example": 245 }, "totalView": { "type": "integer", "description": "Total number of views on the campaign participant's posts", "format": "int64", "example": 754 }, "totalReach": { "type": "integer", "description": "Total number of reach on the campaign participant's posts", "format": "int64", "example": 964 }, "engagementRate": { "type": "number", "description": "The ratio of actions with the posts of the campaign participant to the total reach in percent", "format": "double", "example": 1.91 }, "totalEmvInCents": { "type": "integer", "description": "Total earned media value in cents on the campaign participant's posts", "format": "int64", "example": 964 }, "totalImpressions": { "type": "integer", "description": "Total number of impressions on the campaign participant's posts", "format": "int64", "example": 964 }, "totalShares": { "type": "integer", "description": "Total number of shares on the campaign participant's posts", "format": "int64", "example": 964 }, "totalSaved": { "type": "integer", "description": "Total number of saves on the campaign participant's posts", "format": "int64", "example": 964 } }, "additionalProperties": false }, "OpenApiPost": { "type": "object", "properties": { "postId": { "type": "integer", "description": "The post ID", "format": "int64", "nullable": true, "example": 1254 }, "message": { "$ref": "#/components/schemas/OpenApiMessage" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiImage" }, "nullable": true }, "status": { "$ref": "#/components/schemas/Status" }, "author": { "$ref": "#/components/schemas/OpenApiAuthor" }, "channel": { "$ref": "#/components/schemas/OpenApiChannelBase" }, "viewsCount": { "type": "integer", "description": "The views count", "format": "int32", "example": 54 }, "likes": { "$ref": "#/components/schemas/OpenApiLikes" }, "comments": { "$ref": "#/components/schemas/OpenApiSubComments" }, "hasNewComments": { "type": "boolean", "description": "Indicates the post has new comments since last viewed", "example": true }, "createdAt": { "type": "string", "description": "The date the post was created", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "updatedAt": { "type": "string", "description": "The most recent date the post was updated", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "publishedAt": { "type": "string", "description": "The date the post was published", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "latestActivity": { "type": "string", "description": "The most recent time the post received a comment", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "notifyChannelParticipants": { "type": "boolean", "description": "Indicates if channel participants will be notified when the post is published", "example": true }, "pinnedDate": { "type": "string", "description": "The date the post was pinned", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" } }, "additionalProperties": false }, "OpenApiPostCreateRequest": { "required": [ "channelId", "status", "userId" ], "type": "object", "properties": { "message": { "$ref": "#/components/schemas/OpenApiMessage" }, "channelId": { "type": "integer", "description": "The post’s channel ID", "format": "int32", "example": 142 }, "notifyChannelParticipants": { "type": "boolean", "description": "Indicates if channel participants will be notified when the post is published", "example": true }, "status": { "$ref": "#/components/schemas/CreatePostStatus" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/PostRequestImageObject" }, "nullable": true }, "userId": { "type": "integer", "description": "The post’s author ID", "format": "int64", "example": 1000035 } }, "additionalProperties": false }, "OpenApiPostOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiPost" } }, "additionalProperties": false }, "OpenApiPostPaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiPost" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiPostPaginatedResultOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiPostPaginatedResult" } }, "additionalProperties": false }, "OpenApiPostUpdateRequest": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/OpenApiMessage" }, "channelId": { "type": "integer", "description": "The post’s channel ID", "format": "int32", "nullable": true, "example": 142 }, "status": { "$ref": "#/components/schemas/UpdatePostStatus" }, "notifyChannelParticipants": { "type": "boolean", "description": "Indicates if channel participants will be notified when the post is published", "nullable": true, "example": true }, "addImages": { "type": "array", "items": { "$ref": "#/components/schemas/PostRequestImageObject" }, "nullable": true }, "removeImages": { "type": "array", "items": { "$ref": "#/components/schemas/PostRequestRemovedImageObject" }, "nullable": true } }, "additionalProperties": false }, "OpenApiProfileUpsertRequest": { "type": "object", "properties": { "bio": { "type": "string", "nullable": true }, "displayName": { "type": "string", "nullable": true }, "imageBase64": { "type": "string", "nullable": true }, "imageUpdated": { "type": "boolean", "nullable": true } }, "additionalProperties": false }, "OpenApiProgram": { "type": "object", "properties": { "programId": { "type": "integer", "description": "The program ID", "format": "int32", "example": 1254 }, "name": { "type": "string", "description": "The program name", "nullable": true, "example": "Ambassadors" }, "key": { "type": "string", "description": "The program unique identifier when integrating with 3rd party data", "nullable": true, "example": "roster-ambassadors" }, "color": { "description": "The program colors", "nullable": true }, "icon": { "type": "string", "description": "The program icon name", "nullable": true, "example": "award" }, "ambassadorsCount": { "type": "integer", "description": "The total count of approved ambassadors in the program", "format": "int32", "example": 270 }, "pendingApplicantsCount": { "type": "integer", "description": "The total count of pending applicants in the program", "format": "int32", "example": 270 }, "nominatedApplicantsCount": { "type": "integer", "description": "The total count of nominated applicants in the program", "format": "int32", "example": 32 }, "rejectedApplicantsCount": { "type": "integer", "description": "The total count of rejected applicants in the program", "format": "int32", "example": 6 }, "createdAt": { "type": "string", "description": "The date the program was created", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "updatedAt": { "type": "string", "description": "The most recent date the program was updated", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "status": { "$ref": "#/components/schemas/ProgramStatus" } }, "additionalProperties": false }, "OpenApiProgramAmbassador": { "type": "object", "properties": { "programId": { "type": "integer", "description": "The program ID", "format": "int32", "example": 1254 }, "ambassador": { "$ref": "#/components/schemas/OpenApiContactBase" }, "dateAdded": { "type": "string", "description": "The timestamp the ambassador was added to the program", "format": "date-time", "example": "2022-10-31T11:59:00" }, "createdAt": { "type": "string", "description": "The timestamp the ambassador record was created", "format": "date-time", "example": "2022-10-31T11:59:00" }, "updatedAt": { "type": "string", "description": "The most recent timestamp the ambassador record was updated", "format": "date-time", "example": "2022-10-31T11:59:00" } }, "additionalProperties": false }, "OpenApiProgramAmbassadorDeleteRequest": { "type": "object", "properties": { "contactIds": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "One or more contact IDs to be removed from the program", "nullable": true, "example": [ 238, 3983, 9382 ] } }, "additionalProperties": false }, "OpenApiProgramAmbassadorPaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiProgramAmbassador" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiProgramAmbassadorPostRequest": { "type": "object", "properties": { "contactIds": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "One or more contact IDs to be added", "nullable": true, "example": [ 238, 3983, 9382 ] }, "suppressEmail": { "type": "boolean", "description": "(optional) Suppresses the \"Manually added to program email\", if enabled.", "nullable": true, "example": 1254 } }, "additionalProperties": false }, "OpenApiProgramApplicant": { "type": "object", "properties": { "programId": { "type": "integer", "description": "The program ID", "format": "int32", "example": 1254 }, "applicant": { "$ref": "#/components/schemas/OpenApiContactBase" }, "status": { "$ref": "#/components/schemas/ProgramApplicantStatus" }, "statusDate": { "type": "string", "description": "The timestamp the current applicant status was set", "format": "date-time", "example": "2022-10-31T11:59:00" }, "appliedDate": { "type": "string", "description": "The timestamp the applicant applied to the program", "format": "date-time", "example": "2022-10-31T11:59:00" }, "createdAt": { "type": "string", "description": "The timestamp the applicant record was created", "format": "date-time", "example": "2022-10-31T11:59:00" }, "updatedAt": { "type": "string", "description": "The most recent timestamp the applicant record was updated", "format": "date-time", "example": "2022-10-31T11:59:00" } }, "additionalProperties": false }, "OpenApiProgramApplicantDetails": { "type": "object", "properties": { "programId": { "type": "integer", "description": "The program ID", "format": "int32", "example": 1254 }, "applicant": { "$ref": "#/components/schemas/OpenApiContactBase" }, "status": { "$ref": "#/components/schemas/ProgramApplicantStatus" }, "statusDate": { "type": "string", "description": "The timestamp the current applicant status was set", "format": "date-time", "example": "2022-10-31T11:59:00" }, "appliedDate": { "type": "string", "description": "The timestamp the applicant applied to the program", "format": "date-time", "example": "2022-10-31T11:59:00" }, "createdAt": { "type": "string", "description": "The timestamp the applicant record was created", "format": "date-time", "example": "2022-10-31T11:59:00" }, "updatedAt": { "type": "string", "description": "The most recent timestamp the applicant record was updated", "format": "date-time", "example": "2022-10-31T11:59:00" }, "formUrl": { "type": "string", "description": "The application form Url", "nullable": true, "example": "1254" }, "formUrlParams": { "type": "string", "description": "The url parameters used when the application form was submitted", "nullable": true, "example": "1254" }, "formResponses": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiCustomProperty" }, "description": "The data entry provided by the ambassador when filling out the application form", "nullable": true } }, "additionalProperties": false }, "OpenApiProgramApplicantDetailsOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiProgramApplicantDetails" } }, "additionalProperties": false }, "OpenApiProgramApplicantPaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiProgramApplicant" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiProgramApplicantPostRequest": { "required": [ "email" ], "type": "object", "properties": { "email": { "minLength": 1, "type": "string", "description": "The applicant's email address", "format": "email", "example": "jane.doe@example.com" }, "firstName": { "type": "string", "description": "The applicant's first name", "nullable": true, "example": "Jane" }, "lastName": { "type": "string", "description": "The applicant's last name", "nullable": true, "example": "Doe" }, "phoneNumber": { "type": "string", "description": "The applicant's phone number", "nullable": true, "example": "+15551234567" }, "birthday": { "type": "string", "description": "The applicant's date of birth", "format": "date-time", "nullable": true, "example": "1990-06-15" }, "shippingAddress": { "$ref": "#/components/schemas/OpenApiAddress" }, "paymentMethod": { "$ref": "#/components/schemas/OpenApiApplicantPaymentMethod" }, "socialProfiles": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiApplicantSocialProfile" }, "description": "The applicant's social media profiles. Use the NetworkType values returned by the form definition endpoint.", "nullable": true }, "properties": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiApplicantProperty" }, "description": "Values for custom properties on the application form. Use the PropertyId from the form definition endpoint.", "nullable": true }, "status": { "$ref": "#/components/schemas/OpenApiApplicantStatus" }, "suppressEmail": { "type": "boolean", "description": "When true, suppresses the notification email to the applicant", "nullable": true, "example": false } }, "additionalProperties": false, "description": "Request to add a new applicant to a program" }, "OpenApiProgramApplicationForm": { "type": "object", "properties": { "link": { "type": "string", "description": "The link to the program application form", "nullable": true, "example": "https://apply.getroster.com/agOfh895j" }, "status": { "$ref": "#/components/schemas/ProgramAplicationFormStatus" } }, "additionalProperties": false }, "OpenApiProgramExtended": { "type": "object", "properties": { "programId": { "type": "integer", "description": "The program ID", "format": "int32", "example": 1254 }, "name": { "type": "string", "description": "The program name", "nullable": true, "example": "Ambassadors" }, "key": { "type": "string", "description": "The program unique identifier when integrating with 3rd party data", "nullable": true, "example": "roster-ambassadors" }, "color": { "description": "The program colors", "nullable": true }, "icon": { "type": "string", "description": "The program icon name", "nullable": true, "example": "award" }, "ambassadorsCount": { "type": "integer", "description": "The total count of approved ambassadors in the program", "format": "int32", "example": 270 }, "pendingApplicantsCount": { "type": "integer", "description": "The total count of pending applicants in the program", "format": "int32", "example": 270 }, "nominatedApplicantsCount": { "type": "integer", "description": "The total count of nominated applicants in the program", "format": "int32", "example": 32 }, "rejectedApplicantsCount": { "type": "integer", "description": "The total count of rejected applicants in the program", "format": "int32", "example": 6 }, "createdAt": { "type": "string", "description": "The date the program was created", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "updatedAt": { "type": "string", "description": "The most recent date the program was updated", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "status": { "$ref": "#/components/schemas/ProgramStatus" }, "applicationForm": { "$ref": "#/components/schemas/OpenApiProgramApplicationForm" }, "personalDiscountRule": { "type": "integer", "description": "The program personal discount rule id", "format": "int64", "nullable": true, "example": 119 }, "shareableDiscountRule": { "type": "integer", "description": "The program shearable discount rule id", "format": "int64", "nullable": true, "example": 120 }, "smartLink": { "$ref": "#/components/schemas/OpenApiProgramSmartLink" }, "referralCommissions": { "$ref": "#/components/schemas/OpenApiProgramReferralSetting" }, "referralPoints": { "$ref": "#/components/schemas/OpenApiProgramReferralSetting" } }, "additionalProperties": false }, "OpenApiProgramExtendedOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiProgramExtended" } }, "additionalProperties": false }, "OpenApiProgramListOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiProgram" }, "description": "The response object", "nullable": true, "example": null } }, "additionalProperties": false }, "OpenApiProgramPerformanceCard": { "type": "object", "properties": { "section": { "type": "string", "description": "The dashboard section the card sits in", "nullable": true }, "metric": { "type": "string", "description": "The metric key (e.g. post_emv, members, referred_revenue)", "nullable": true }, "title": { "type": "string", "description": "The card title as shown on the dashboard", "nullable": true }, "data": { "description": "The card's data, exactly as the portal dashboard receives it\r\n(time series plus period totals and deltas; shape varies per metric)", "nullable": true } }, "additionalProperties": false }, "OpenApiProgramPerformanceDateRange": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "OpenApiProgramPerformanceProgram": { "type": "object", "properties": { "programId": { "type": "integer", "format": "int64" }, "name": { "type": "string", "nullable": true } }, "additionalProperties": false }, "OpenApiProgramPerformanceResponse": { "type": "object", "properties": { "program": { "$ref": "#/components/schemas/OpenApiProgramPerformanceProgram" }, "dateRange": { "$ref": "#/components/schemas/OpenApiProgramPerformanceDateRange" }, "dashboardCards": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiProgramPerformanceCard" }, "nullable": true } }, "additionalProperties": false }, "OpenApiProgramPerformanceResponseOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiProgramPerformanceResponse" } }, "additionalProperties": false }, "OpenApiProgramReferralSetting": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ReferralRewardSettingType" }, "amount": { "type": "number", "description": "The default reward amount. For percentage, this is a number (e.g., 15 for 15%). \r\nFor fixed_amount, this is the monetary value or points.", "format": "double", "nullable": true, "example": 15 }, "differentiateCustomerType": { "type": "boolean", "description": "Indicates whether different amounts are applied for new vs existing customers.", "example": true }, "newCustomerAmount": { "type": "number", "description": "The reward amount for new customers. Only used when DifferentiateCustomerType is true.", "format": "double", "nullable": true, "example": 20 }, "existingCustomerAmount": { "type": "number", "description": "The reward amount for existing customers. Only used when DifferentiateCustomerType is true.", "format": "double", "nullable": true, "example": 10 }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiRewardTier" }, "description": "Tier-based reward configuration. Only used when type is \"tiers\".\r\nShould be null for \"percentage\" and \"fixed_amount\" types.", "nullable": true }, "overrides": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiRewardOverride" }, "description": "Optional list of reward overrides based on contact tags.", "nullable": true }, "approvalMethod": { "$ref": "#/components/schemas/ApprovalMethod" }, "autoApprovalDays": { "type": "integer", "description": "Number of days until automatic approval if approval method supports it.", "format": "int32", "nullable": true, "example": 7 }, "recurring": { "type": "boolean", "description": "Indicates whether this reward is recurring for subscription purchases.", "example": true }, "recurringDays": { "type": "integer", "description": "Number of days for recurring reward calculation, if applicable.", "format": "int32", "nullable": true, "example": 30 } }, "additionalProperties": false }, "OpenApiProgramSmartLink": { "type": "object", "properties": { "destinationUrl": { "type": "string", "description": "The destination URL for the smart link. Supports template variables like {{referralId}}.", "nullable": true }, "attributionWindow": { "type": "integer", "description": "The attribution window in days for tracking conversions.", "format": "int32", "nullable": true }, "customerDiscount": { "$ref": "#/components/schemas/CustomerDiscount" } }, "additionalProperties": false }, "OpenApiReferralOrderDetails": { "type": "object", "properties": { "orderId": { "type": "integer", "description": "The Roster order ID", "format": "int64", "nullable": true, "example": 123456 }, "externalOrderId": { "type": "integer", "description": "The external order ID", "format": "int64", "nullable": true, "example": 123456 }, "externalOrderNumber": { "type": "string", "description": "The external order number", "nullable": true, "example": "123456" }, "orderDate": { "type": "string", "description": "The date the order was created", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "orderSubtotal": { "type": "number", "description": "The subtotal of the referred order", "format": "double", "nullable": true, "example": 25 } }, "additionalProperties": false }, "OpenApiReferralReward": { "type": "object", "properties": { "referralRewardId": { "type": "integer", "description": "The referral reward Id", "format": "int64", "example": 123456 }, "attributionId": { "type": "integer", "description": "The attribution ID", "format": "int64", "nullable": true, "example": 123456 }, "orderDetails": { "$ref": "#/components/schemas/OpenApiReferralOrderDetails" }, "ambassador": { "$ref": "#/components/schemas/OpenApiContactBase" }, "rewardType": { "$ref": "#/components/schemas/ReferralRewardType" }, "rewardValue": { "type": "number", "description": "The referral reward's amount", "format": "double", "example": 10 }, "rewardSettings": { "$ref": "#/components/schemas/OpenApiReferralRewardSettings" }, "status": { "$ref": "#/components/schemas/ReferralRewardStatus" }, "internalNote": { "type": "string", "description": "An internal note", "nullable": true, "example": "This is an internal note" }, "ambassadorNote": { "type": "string", "description": "A note shown to the ambassador explaining what the reward is for", "nullable": true, "example": "Cash for your spring campaign UGC video" }, "createdAt": { "type": "string", "description": "The date the referral reward was created", "format": "date-time", "example": "2022-10-31T11:59:00" }, "updatedAt": { "type": "string", "description": "The date the referral reward was last updated", "format": "date-time", "example": "2022-10-31T11:59:00" }, "isPaidTraffic": { "type": "boolean", "description": "Whether the referral reward's originating click came from a paid ad\r\n(detected via gclid, fbclid, etc.). Null when the reward has no attributed\r\nclick (e.g. manual rewards, discount-code / recurring / legacy attributions).", "nullable": true, "example": true }, "paidTrafficSource": { "type": "string", "description": "The detected paid traffic source platform (e.g. google, facebook, tiktok).\r\nNull when the reward is not from paid traffic.", "nullable": true, "example": "facebook" } }, "additionalProperties": false }, "OpenApiReferralRewardOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiReferralReward" } }, "additionalProperties": false }, "OpenApiReferralRewardPaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiReferralReward" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiReferralRewardPaginatedResultOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiReferralRewardPaginatedResult" } }, "additionalProperties": false }, "OpenApiReferralRewardPostRequest": { "required": [ "ambassadorId", "orderDetails" ], "type": "object", "properties": { "orderDetails": { "$ref": "#/components/schemas/ReferralRewardPostReferralDetails" }, "ambassadorId": { "type": "integer", "description": "The ambassador to whom the reward is awarded", "format": "int64", "example": 123456 }, "rewardType": { "$ref": "#/components/schemas/ReferralRewardType" }, "rewardValue": { "type": "number", "description": "The value of the reward", "format": "double", "example": 10 }, "internalNote": { "type": "string", "description": "An internal note describing the reason for the manual referral reward", "nullable": true, "example": "The ambassador had a referral in our physical store" }, "ambassadorNote": { "type": "string", "description": "A note shown to the ambassador explaining what the reward is for. Max 100 characters.", "nullable": true, "example": "Cash for your spring campaign UGC video" }, "status": { "$ref": "#/components/schemas/ReferralRewardStatus" } }, "additionalProperties": false }, "OpenApiReferralRewardPutRequest": { "required": [ "orderDetails" ], "type": "object", "properties": { "orderDetails": { "$ref": "#/components/schemas/ReferralRewardPostReferralDetails" }, "ambassadorId": { "type": "integer", "description": "The ambassador to whom the reward is awarded", "format": "int64", "nullable": true, "example": 123456 }, "rewardType": { "$ref": "#/components/schemas/ReferralRewardType" }, "rewardValue": { "type": "number", "description": "The value of the reward", "format": "double", "nullable": true, "example": 10 }, "internalNote": { "type": "string", "description": "An internal note describing the reason for the manual referral reward", "nullable": true, "example": "The ambassador had a referral in our physical store" }, "ambassadorNote": { "type": "string", "description": "A note shown to the ambassador explaining what the reward is for. Max 100 characters.", "nullable": true, "example": "Cash for your spring campaign UGC video" } }, "additionalProperties": false }, "OpenApiReferralRewardSettings": { "type": "object", "properties": { "rewardSettingId": { "type": "integer", "description": "The reward settings ID", "format": "int64", "example": 123456 }, "programId": { "type": "integer", "description": "The ambassador's program ID", "format": "int32", "example": 12 }, "type": { "$ref": "#/components/schemas/ReferralRewardSettingType" }, "amount": { "type": "number", "description": "The referral reward setting's amount", "format": "double", "example": 10 }, "approvalMethod": { "type": "string", "description": "The approval method", "nullable": true, "example": "wowowow" }, "recurrence": { "type": "boolean", "description": "Whether this reward is a recurring reward or not", "example": true }, "startDate": { "type": "string", "description": "The referral reward's start date", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" }, "endDate": { "type": "string", "description": "The referral reward's end date", "format": "date-time", "nullable": true, "example": "2022-10-31T11:59:00" } }, "additionalProperties": false }, "OpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null } }, "additionalProperties": false }, "OpenApiReward": { "type": "object", "properties": { "id": { "type": "integer", "description": "The reward ID", "format": "int64", "example": 123456 }, "ambassador": { "$ref": "#/components/schemas/OpenApiContactProgramBase" }, "type": { "$ref": "#/components/schemas/RewardType" }, "status": { "$ref": "#/components/schemas/RewardFulfillmentStatus" }, "rewardStatusId": { "type": "integer", "description": "The raw status id. Reward statuses come from two deliberately separate value spaces:\r\nfulfilment (601 Pending / 276 Fulfilled / 602 Won't fulfill / 894 Redeemed / 895 Not\r\nredeemed / 1258 Redemption failed) and money (530 Pending / 536 Approved / 537 Paid /\r\n538 Rejected). Cash rewards use the money ladder, so App.OpenApi.Domain.Models.Base.Engagement.Rewards.OpenApiRewardBase.Status cannot represent\r\nthem - branch on the reward type and read this instead.", "format": "int32", "example": 530 }, "cashAmount": { "type": "number", "description": "The cash value of this reward, or null when it is not a cash reward. Null is the\r\ndiscriminator: a points or product reward has no amount at all, which is different from an\r\namount of zero, and must never be rendered as money.", "format": "double", "nullable": true, "example": 50 }, "statusDate": { "type": "string", "description": "The date the status was modified", "format": "date-time", "nullable": true }, "rewardTemplate": { "$ref": "#/components/schemas/OpenApiRewardTemplate" }, "discountCode": { "$ref": "#/components/schemas/OpenApiRewardDiscountCode" }, "order": { "$ref": "#/components/schemas/OpenApiRewardOrder" }, "createdAt": { "type": "string", "description": "The timestamp the reward was created", "format": "date-time", "example": "2022-10-31T11:59:00" }, "updatedAt": { "type": "string", "description": "The most recent timestamp the reward was updated", "format": "date-time", "example": "2022-10-31T11:59:00" }, "source": { "$ref": "#/components/schemas/RewardSource" }, "sourceId": { "type": "integer", "description": "The reward Source ID", "format": "int64", "example": 123456 } }, "additionalProperties": false }, "OpenApiRewardCustomProperty": { "type": "object", "properties": { "propertyId": { "type": "integer", "description": "The ID for the property", "format": "int64", "example": 1254 }, "value": { "description": "The data entry provided by the ambassador when filling out the application form. Can be a dynamic json object or string.", "nullable": true }, "valueString": { "type": "string", "description": "The string representation of the `value` object.", "nullable": true }, "label": { "type": "string", "nullable": true } }, "additionalProperties": false }, "OpenApiRewardDiscountCode": { "type": "object", "properties": { "discountRuleId": { "type": "integer", "description": "The discount rule ID", "format": "int64", "example": 123456 }, "code": { "type": "string", "description": "The discount code", "nullable": true, "example": "abc_CODE" } }, "additionalProperties": false }, "OpenApiRewardMilestone": { "type": "object", "properties": { "milestoneId": { "type": "integer", "description": "The Milestone ID", "format": "int64", "nullable": true }, "name": { "type": "string", "description": "The milestone name", "nullable": true, "example": "some Product" }, "dateUnlocked": { "type": "string", "description": "The date milestone was unlocked", "format": "date-time", "nullable": true, "example": "some Product" } }, "additionalProperties": false }, "OpenApiRewardOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiReward" } }, "additionalProperties": false }, "OpenApiRewardOrder": { "type": "object", "properties": { "orderId": { "type": "integer", "description": "The Roster order ID", "format": "int64", "nullable": true, "example": 123456 }, "externalOrderId": { "type": "string", "description": "The external order ID (e.g. the Shopify order ID)", "nullable": true, "example": "209834573494" }, "externalOrderNumber": { "type": "string", "description": "The external system's order number", "nullable": true, "example": "84524" }, "fulfillmentStatus": { "$ref": "#/components/schemas/OrderFulfillmentStatus" }, "isDraftOrder": { "type": "boolean", "description": "Whether or not the order is currently in a draft order state." }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Errors from order completion.", "nullable": true } }, "additionalProperties": false }, "OpenApiRewardOverride": { "type": "object", "properties": { "contactTags": { "type": "string", "description": "Comma-separated list of contact tags that trigger this override.", "nullable": true, "example": " \"vip,pros\" " }, "amount": { "type": "number", "description": "The override reward amount for contacts with matching tags.\r\nUsed when DifferentiateCustomerType is false.", "format": "double", "nullable": true, "example": "10.00" }, "newCustomerAmount": { "type": "number", "description": "The override amount for new customers with matching tags.\r\nUsed when DifferentiateCustomerType is true.", "format": "double", "nullable": true, "example": "15.00" }, "existingCustomerAmount": { "type": "number", "description": "The override amount for existing customers with matching tags.\r\nUsed when DifferentiateCustomerType is true.", "format": "double", "nullable": true, "example": "8.00" } }, "additionalProperties": false, "description": "Represents a reward override based on contact tags." }, "OpenApiRewardPaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiReward" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiRewardStatusFailed": { "type": "object", "properties": { "rewardIds": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "Failed reward Ids", "nullable": true }, "message": { "type": "string", "description": "Reason of status update failure", "nullable": true } }, "additionalProperties": false }, "OpenApiRewardStatusUpdate": { "type": "object", "properties": { "failedRewards": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiRewardStatusFailed" }, "description": "Failed rewards list", "nullable": true } }, "additionalProperties": false }, "OpenApiRewardStatusUpdateOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiRewardStatusUpdate" } }, "additionalProperties": false }, "OpenApiRewardTemplate": { "type": "object", "properties": { "id": { "type": "integer", "description": "The reward template system unique ID", "format": "int64", "nullable": true, "example": 6549 }, "name": { "type": "string", "description": "The reward template name", "nullable": true, "example": "Gold milestone reward" }, "value": { "type": "number", "description": "The reward template value", "format": "double", "nullable": true, "example": 4.45 }, "description": { "type": "string", "description": "The reward template description", "nullable": true, "example": "qwerty" }, "url": { "type": "string", "description": "The reward template URL", "nullable": true }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiImage" }, "description": "The reward template images", "nullable": true } }, "additionalProperties": false }, "OpenApiRewardTemplateDetails": { "type": "object", "properties": { "id": { "type": "integer", "description": "The reward template system unique ID", "format": "int64", "nullable": true, "example": 6549 }, "name": { "type": "string", "description": "The reward template name", "nullable": true, "example": "Gold milestone reward" }, "rewardType": { "$ref": "#/components/schemas/RewardType" }, "campaign": { "$ref": "#/components/schemas/LinkedObject" }, "milestoneSeries": { "$ref": "#/components/schemas/LinkedObject" }, "createdAt": { "type": "string", "description": "Reward template's created at or after timestamp. Date ISO 8601", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "description": "Reward template's created at or before timestamp. Date ISO 8601", "format": "date-time", "nullable": true }, "value": { "type": "number", "description": "The reward template value", "format": "double", "nullable": true, "example": 4.45 }, "description": { "type": "string", "description": "The reward template description", "nullable": true, "example": "qwerty" }, "url": { "type": "string", "description": "The reward template URL", "nullable": true }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiImage" }, "description": "The reward template images", "nullable": true }, "productGroups": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiRewardTemplateProductGroup" }, "description": "Reward template product groups", "nullable": true }, "manualRewardStats": { "$ref": "#/components/schemas/ManualRewardTemplateStats" }, "automatedRewardStats": { "$ref": "#/components/schemas/AutomatedRewardTemplateStats" }, "jsonData": { "description": "Reward template JSON data", "nullable": true }, "rewardTemplateIssuance": { "$ref": "#/components/schemas/RewardTemplateIssuance" } }, "additionalProperties": false }, "OpenApiRewardTemplateDetailsOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiRewardTemplateDetails" } }, "additionalProperties": false }, "OpenApiRewardTemplateProductGroup": { "type": "object", "properties": { "productGroupTitle": { "type": "string", "description": "The product group title", "nullable": true }, "limit": { "$ref": "#/components/schemas/OpenApiRewardTemplateProductGroupLimit" }, "collectionsCount": { "type": "integer", "description": "The total number of collections in the group", "format": "int32", "nullable": true }, "productsCount": { "type": "integer", "description": "The total number of products in the group", "format": "int32", "nullable": true } }, "additionalProperties": false }, "OpenApiRewardTemplateProductGroupLimit": { "type": "object", "properties": { "type": { "type": "string", "description": "The product group limit type", "nullable": true }, "value": { "type": "number", "description": "The product group limit value", "format": "float", "nullable": true } }, "additionalProperties": false }, "OpenApiRewardTemplateSummary": { "type": "object", "properties": { "id": { "type": "integer", "description": "The reward template system unique ID", "format": "int64", "nullable": true, "example": 6549 }, "name": { "type": "string", "description": "The reward template name", "nullable": true, "example": "Gold milestone reward" }, "rewardType": { "$ref": "#/components/schemas/RewardType" }, "campaign": { "$ref": "#/components/schemas/LinkedObject" }, "milestoneSeries": { "$ref": "#/components/schemas/LinkedObject" }, "createdAt": { "type": "string", "description": "Reward template's created at or after timestamp. Date ISO 8601", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "description": "Reward template's created at or before timestamp. Date ISO 8601", "format": "date-time", "nullable": true }, "rewardStats": { "$ref": "#/components/schemas/ManualRewardTemplateStats" } }, "additionalProperties": false }, "OpenApiRewardTemplateSummaryPaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiRewardTemplateSummary" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiRewardTier": { "type": "object", "properties": { "sequence": { "type": "integer", "description": "The sequence/order of the tier.", "format": "int32", "example": 1 }, "from": { "type": "number", "description": "The starting value of the tier range (inclusive).", "format": "double", "example": "0.00" }, "to": { "type": "number", "description": "The ending value of the tier range (inclusive).", "format": "double", "example": "1000.00" }, "amount": { "type": "number", "description": "The reward amount for this tier.", "format": "double", "example": "15.00" }, "name": { "type": "string", "description": "The display name for this tier.", "nullable": true, "example": " \"Tier 1\" " } }, "additionalProperties": false, "description": "Represents a tier configuration for tiered reward calculations." }, "OpenApiSalesAttributionAmbassador": { "type": "object", "properties": { "contactId": { "type": "integer", "format": "int64" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } }, "additionalProperties": false }, "OpenApiSalesAttributionReportResponse": { "type": "object", "properties": { "totals": { "$ref": "#/components/schemas/OpenApiSalesAttributionTotals" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiSalesAttributionRow" }, "nullable": true } }, "additionalProperties": false, "description": "The Sales Attribution report: grand totals plus one row per ambassador\r\nwith activity in the date range" }, "OpenApiSalesAttributionReportResponsePaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiSalesAttributionReportResponse" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiSalesAttributionRow": { "type": "object", "properties": { "ambassador": { "$ref": "#/components/schemas/OpenApiSalesAttributionAmbassador" }, "totalClicks": { "type": "integer", "format": "int32" }, "newCustomers": { "type": "integer", "format": "int32" }, "referredOrders": { "type": "integer", "format": "int32" }, "referredRevenue": { "type": "number", "format": "double" }, "referralCommissions": { "type": "number", "format": "double" }, "referralPoints": { "type": "number", "format": "double" }, "personalOrders": { "type": "integer", "format": "int32" }, "personalOrderRevenue": { "type": "number", "format": "double" }, "shareableCodes": { "type": "string", "nullable": true }, "referralLink": { "type": "string", "nullable": true }, "currency": { "type": "string", "nullable": true }, "tags": { "type": "string", "nullable": true } }, "additionalProperties": false }, "OpenApiSalesAttributionSortField": { "enum": [ "referredRevenue", "totalClicks", "newCustomers", "referredOrders", "personalOrders", "personalOrderRevenue" ], "type": "string", "description": "Sortable columns of the Sales Attribution report" }, "OpenApiSalesAttributionTotals": { "type": "object", "properties": { "totalClicks": { "type": "integer", "format": "int32" }, "newCustomers": { "type": "integer", "format": "int32" }, "referredRevenue": { "type": "number", "format": "double" }, "personalOrderRevenue": { "type": "number", "format": "double" }, "totalRevenue": { "type": "number", "format": "double" }, "rowCount": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "OpenApiSocialFeedEmv": { "type": "object", "properties": { "total": { "type": "number", "format": "double" }, "impressions": { "type": "number", "format": "double" }, "likes": { "type": "number", "format": "double" }, "comments": { "type": "number", "format": "double" }, "shares": { "type": "number", "format": "double" }, "saves": { "type": "number", "format": "double" } }, "additionalProperties": false }, "OpenApiSocialFeedMetrics": { "type": "object", "properties": { "likes": { "type": "integer", "format": "int32" }, "comments": { "type": "integer", "format": "int32" }, "shares": { "type": "integer", "format": "int32" }, "saves": { "type": "integer", "format": "int32" }, "videoViews": { "type": "integer", "format": "int32" }, "impressions": { "type": "integer", "format": "int32" }, "reach": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "OpenApiSocialFeedPost": { "type": "object", "properties": { "postId": { "type": "string", "nullable": true }, "platform": { "type": "string", "nullable": true }, "postType": { "type": "string", "nullable": true }, "ambassador": { "$ref": "#/components/schemas/OpenApiSalesAttributionAmbassador" }, "program": { "$ref": "#/components/schemas/OpenApiSocialFeedProgram" }, "postedAt": { "type": "string", "format": "date-time", "nullable": true }, "caption": { "type": "string", "nullable": true }, "permalink": { "type": "string", "nullable": true }, "mediaUrl": { "type": "string", "nullable": true }, "metrics": { "$ref": "#/components/schemas/OpenApiSocialFeedMetrics" }, "emv": { "$ref": "#/components/schemas/OpenApiSocialFeedEmv" } }, "additionalProperties": false }, "OpenApiSocialFeedPostPaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiSocialFeedPost" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiSocialFeedProgram": { "type": "object", "properties": { "programId": { "type": "integer", "format": "int64" }, "name": { "type": "string", "nullable": true } }, "additionalProperties": false }, "OpenApiSocialFeedSort": { "enum": [ "postDate", "engagement", "followers" ], "type": "string" }, "OpenApiSocialPostNetwork": { "enum": [ "x", "instagram", "facebook", "tikTok" ], "type": "string", "description": "Social networks covered by social listening" }, "OpenApiSocialPostsReportResponse": { "type": "object", "properties": { "totals": { "$ref": "#/components/schemas/OpenApiSocialPostsTotals" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiSocialPostsRow" }, "nullable": true } }, "additionalProperties": false, "description": "The Social Posts report: grand totals plus one row per ambassador who\r\nposted in the date range" }, "OpenApiSocialPostsReportResponsePaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiSocialPostsReportResponse" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "OpenApiSocialPostsRow": { "type": "object", "properties": { "ambassador": { "$ref": "#/components/schemas/OpenApiSalesAttributionAmbassador" }, "posts": { "type": "integer", "format": "int32" }, "stories": { "type": "integer", "format": "int32" }, "reach": { "type": "number", "format": "double" }, "impressions": { "type": "integer", "format": "int32" }, "likes": { "type": "integer", "format": "int32" }, "comments": { "type": "integer", "format": "int32" }, "shares": { "type": "integer", "format": "int32" }, "saves": { "type": "integer", "format": "int32" }, "emv": { "type": "number", "format": "double" }, "engagement": { "type": "number", "format": "double" }, "engagementRate": { "type": "number", "format": "double" } }, "additionalProperties": false }, "OpenApiSocialPostsSortField": { "enum": [ "posts", "stories", "reach", "impressions", "likes", "comments", "shares", "saves", "emv", "engagementRate" ], "type": "string", "description": "Sortable columns of the Social Posts report" }, "OpenApiSocialPostsTotals": { "type": "object", "properties": { "posts": { "type": "integer", "format": "int32" }, "stories": { "type": "integer", "format": "int32" }, "reach": { "type": "number", "format": "double" }, "impressions": { "type": "integer", "format": "int32" }, "engagement": { "type": "number", "format": "double" }, "engagementRate": { "type": "number", "format": "double" }, "emv": { "type": "number", "format": "double" }, "ambassadorCount": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "OpenApiSubComments": { "type": "object", "properties": { "latestComments": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiComment" }, "description": "The two latest comments", "nullable": true }, "count": { "type": "integer", "description": "The total count of comments", "format": "int32" } }, "additionalProperties": false }, "OpenApiUserBase": { "type": "object", "properties": { "userId": { "type": "integer", "description": "The user's system generated unique ID", "format": "int64", "nullable": true, "example": 123456 }, "firstName": { "type": "string", "description": "The user's first name", "nullable": true, "example": "Frodo" }, "lastName": { "type": "string", "description": "The user's last name", "nullable": true, "example": "Baggins" }, "emailAddress": { "type": "string", "description": "The user's email address", "nullable": true, "example": "example@email.com" }, "profileImageUrl": { "type": "string", "description": "The user's profile image uri", "nullable": true, "example": "https://www.example.com/image.jpg" } }, "additionalProperties": false }, "OpenApiUserType": { "enum": [ "teamMember", "contact" ], "type": "string" }, "OpenApiWebhook": { "type": "object", "properties": { "webhookId": { "type": "integer", "description": "The webhook's system generated unique ID", "format": "int64", "example": 123456 }, "address": { "type": "string", "description": "The destination URI to which the webhook subscription should send the POST request when an event occurs.", "nullable": true, "example": "`https://my.app.com/webhook/listener`" }, "topic": { "type": "string", "description": "The event that triggers the webhook.", "nullable": true, "example": "'reward/redeemed'" }, "customData": { "description": "The webhook specific data to be sent with each event.", "nullable": true }, "createdAt": { "type": "string", "description": "The date and time the link click was captured", "format": "date-time", "example": "2022-10-31T11:59:00" }, "updatedAt": { "type": "string", "description": "The date and time the link click was captured", "format": "date-time", "example": "2022-10-31T11:59:00" } }, "additionalProperties": false }, "OpenApiWebhookOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/OpenApiWebhook" } }, "additionalProperties": false }, "OpenApiWebhookPaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenApiWebhook" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "Order": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "userCustomerOrderId": { "type": "integer", "format": "int64", "nullable": true }, "networkType": { "$ref": "#/components/schemas/SocialNetwork" }, "sourceUniqueId": { "type": "string", "nullable": true }, "sourceOrderNumber": { "type": "string", "nullable": true }, "statusId": { "type": "integer", "format": "int32" }, "financialStatusId": { "type": "integer", "format": "int32", "nullable": true }, "fulfillmentStatusId": { "type": "integer", "format": "int32", "nullable": true }, "currency": { "$ref": "#/components/schemas/Currency" }, "subtotalPrice": { "type": "number", "format": "double", "nullable": true }, "totalPrice": { "type": "number", "format": "double", "nullable": true }, "orderItems": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" }, "nullable": true }, "settings": { "type": "array", "items": { "$ref": "#/components/schemas/OrderSetting" }, "nullable": true }, "modifyDate": { "type": "string", "format": "date-time" }, "cancelledDate": { "type": "string", "format": "date-time", "nullable": true }, "orderDate": { "type": "string", "format": "date-time", "nullable": true }, "discountCodes": { "type": "array", "items": { "type": "string" }, "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "nullable": true }, "isNewCustomer": { "type": "boolean", "nullable": true }, "externalOrderStatusUrl": { "type": "string", "nullable": true }, "rawData": { "nullable": true }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/UserCustomerOrderMetadata" }, "nullable": true }, "invoiceUrl": { "type": "string", "nullable": true }, "totalShippingPriceSet": { "$ref": "#/components/schemas/OrderPriceSet" }, "draftOrderId": { "type": "string", "nullable": true }, "landingSite": { "type": "string", "nullable": true }, "noteAttributes": { "type": "array", "items": { "$ref": "#/components/schemas/OrderNoteAttribute" }, "nullable": true }, "orderSourceName": { "type": "string", "nullable": true }, "hasSubscriptionLineItems": { "type": "boolean", "nullable": true }, "orderTagsJson": { "type": "string", "nullable": true }, "orderAppId": { "type": "string", "nullable": true }, "orderAppName": { "type": "string", "nullable": true } }, "additionalProperties": false }, "OrderFinancialStatus": { "enum": [ "none", "paid", "partiallyRefunded", "refunded" ], "type": "string" }, "OrderFulfillmentStatus": { "enum": [ "none", "fulfilled", "partiallyFulfilled", "restocked" ], "type": "string" }, "OrderItem": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "sourceUniqueId": { "type": "string", "nullable": true }, "variantSourceUniqueId": { "type": "string", "nullable": true }, "userProductId": { "type": "integer", "format": "int64", "nullable": true }, "name": { "type": "string", "nullable": true }, "quantity": { "type": "integer", "format": "int32" }, "unfulfilledQuantity": { "type": "integer", "format": "int32" }, "sku": { "type": "string", "nullable": true }, "imageUrl": { "type": "string", "nullable": true }, "price": { "type": "number", "format": "double" }, "productSourceUniqueId": { "type": "string", "nullable": true }, "discountedPrice": { "type": "number", "format": "double", "nullable": true }, "inventoryQuantity": { "type": "integer", "format": "int32" }, "options": { "type": "array", "items": { "type": "string" }, "nullable": true }, "groupIndex": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "OrderNoteAttribute": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "value": { "type": "string", "nullable": true } }, "additionalProperties": false }, "OrderPriceSet": { "type": "object", "properties": { "amount": { "type": "number", "format": "double" }, "currencyCode": { "type": "string", "nullable": true } }, "additionalProperties": false }, "OrderSetting": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "type": { "$ref": "#/components/schemas/Lookup" }, "value": { "nullable": true } }, "additionalProperties": false }, "OrderSorter": { "enum": [ "orderDate", "orderNumber", "orderRevenue", "orderTotal" ], "type": "string" }, "OrderStatus": { "enum": [ "none", "created", "fulfilled", "canceled" ], "type": "string" }, "Pagination": { "type": "object", "properties": { "pageIndex": { "type": "integer", "description": "The page index", "format": "int32" }, "pageSize": { "type": "integer", "description": "Records per page", "format": "int32" }, "totalRecords": { "type": "integer", "description": "Total records in the result set", "format": "int32", "example": 20 }, "totalUnfilteredRecords": { "type": "integer", "description": "Overall total unfiltered records", "format": "int32", "nullable": true }, "totalPages": { "type": "integer", "description": "Total pages in the result set", "format": "int32", "readOnly": true }, "nextPageIndex": { "type": "integer", "description": "Next page index", "format": "int32", "nullable": true, "readOnly": true } }, "additionalProperties": false }, "ParentType": { "enum": [ "comment", "post" ], "type": "string" }, "ParticipantSorter": { "enum": [ "ambassador", "posts", "comments", "likesReceived", "likesGiven", "latestActivity", "dateAdded", "displayName" ], "type": "string" }, "PinnedFilter": { "enum": [ "pinnedPosts", "unpinnedPosts" ], "type": "string" }, "PostRequestImageObject": { "type": "object", "properties": { "base64": { "type": "string", "description": "Base64 format of an image", "nullable": true, "example": "/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAIBAQIBAQICAg..." }, "contentType": { "type": "string", "description": "The type of a new image", "nullable": true, "example": "image/png" }, "filename": { "type": "string", "description": "The name of an image", "nullable": true, "example": "image.png" } }, "additionalProperties": false }, "PostRequestRemovedImageObject": { "type": "object", "properties": { "resourceId": { "type": "integer", "description": "The id of an image resource, if null then will be created a new resource", "format": "int32", "nullable": true, "example": 189 } }, "additionalProperties": false }, "PostTag": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true } }, "additionalProperties": false }, "ProgramAplicationFormStatus": { "enum": [ "live", "closed" ], "type": "string" }, "ProgramApplicantSorter": { "enum": [ "appliedDate", "statusDate" ], "type": "string" }, "ProgramApplicantStatus": { "enum": [ "pending", "nominated", "approved", "rejected", "removed" ], "type": "string" }, "ProgramStatus": { "enum": [ "active", "archived" ], "type": "string" }, "ReferralRewardPostReferralDetails": { "required": [ "orderDate" ], "type": "object", "properties": { "externalOrderId": { "type": "integer", "description": "The external order ID", "format": "int64", "nullable": true, "example": 123456 }, "orderDate": { "type": "string", "description": "The date the order was created", "format": "date-time", "example": "2022-10-31T11:59:00" }, "orderSubtotal": { "type": "number", "description": "The subtotal of the order", "format": "double", "nullable": true, "example": 25 } }, "additionalProperties": false }, "ReferralRewardSettingType": { "enum": [ "none", "percentage", "fixed_amount", "tiers" ], "type": "string" }, "ReferralRewardStatus": { "enum": [ "pending", "approved", "paid", "rejected" ], "type": "string" }, "ReferralRewardType": { "enum": [ "none", "points", "commission" ], "type": "string" }, "RewardFulfillmentStatus": { "enum": [ "fulfilled", "pending", "willNotFulfill", "redeemed", "notRedeemed", "redemptionFailed" ], "type": "string", "description": "The reward fulfillment status" }, "RewardSorter": { "enum": [ "ambassador", "createdAt" ], "type": "string" }, "RewardSource": { "enum": [ "milestone", "campaign" ], "type": "string", "description": "The reward source" }, "RewardStatusRequest": { "type": "object", "properties": { "rewardIds": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "The reward(s) to update", "nullable": true }, "status": { "$ref": "#/components/schemas/UpdateRewardStatus" }, "notify": { "type": "boolean", "description": "When true and the status is set to fulfilled, emails the affected ambassador(s)\r\nthat their reward was fulfilled (using the brand's \"reward fulfilled\" template).\r\nIgnored for any status other than fulfilled.", "example": true } }, "additionalProperties": false }, "RewardTemplateIssuance": { "enum": [ "upon_joining", "upon_completing" ], "type": "string" }, "RewardTemplateSorter": { "enum": [ "name", "createdAt", "eligible", "awarded", "needsFulfillment" ], "type": "string" }, "RewardType": { "enum": [ "manualProduct", "custom", "discountCode", "points", "commission", "automatedProduct" ], "type": "string", "description": "The reward type" }, "RuleStatus": { "enum": [ "planned", "active", "expired", "archived" ], "type": "string", "description": "The discount rule status" }, "RuleTypes": { "enum": [ "shareable_code", "reward", "leakproof_code" ], "type": "string", "description": "The discount rule type" }, "SmartLinkDiscountTypes": { "enum": [ "leakproof_code", "shareable", "veeper" ], "type": "string", "description": "The smart link discount type" }, "SocialNetwork": { "enum": [ "none", "twitter", "instagram", "facebook", "csv", "angelList", "vimeo", "flickr", "gravatar", "foursquare", "youTube", "google", "pinterest", "linkedIn", "klout", "aboutMe", "quora", "tumblr", "shopify", "mailChimp", "github", "myspace", "soundCloud", "delicious", "wordpress", "blogger", "yelp", "picasa", "spotify", "yahoo", "reddit", "systemInternal", "facebookPage", "instagramPage", "webLink", "payPal", "tikTok", "chargebee", "instagramReel", "sendGrid", "microsoft", "facebookReel", "dots", "googleDrive", "tikTokBusiness" ], "type": "string" }, "SortDirections": { "enum": [ "asc", "desc" ], "type": "string" }, "Status": { "enum": [ "draft", "published", "scheduled", "archived" ], "type": "string" }, "Token": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "tokenTypeId": { "type": "integer", "format": "int32" }, "expireDate": { "type": "string", "format": "date-time" }, "modifyDate": { "type": "string", "format": "date-time" }, "token": { "type": "string", "nullable": true }, "type": { "$ref": "#/components/schemas/Lookup" }, "userId": { "type": "integer", "format": "int64" }, "tokenSecret": { "type": "string", "nullable": true }, "permissions": { "type": "string", "nullable": true }, "completed": { "type": "boolean" }, "accessExpireDate": { "type": "string", "format": "date-time", "nullable": true }, "udf1": { "type": "string", "nullable": true }, "udf2": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "displayName": { "type": "string", "nullable": true }, "socialProfileId": { "type": "integer", "format": "int64" }, "statusId": { "type": "integer", "format": "int32", "nullable": true }, "lastCharacters": { "type": "string", "nullable": true }, "hasTokenSecret": { "type": "boolean" }, "isExpiringTokenModel": { "type": "boolean", "readOnly": true }, "canRefresh": { "type": "boolean", "readOnly": true }, "isExpired": { "type": "boolean", "readOnly": true }, "socialNetwork": { "$ref": "#/components/schemas/SocialNetwork" }, "url": { "type": "string", "nullable": true, "readOnly": true } }, "additionalProperties": false }, "UnassignedCodeImport": { "required": [ "code" ], "type": "object", "properties": { "code": { "minLength": 1, "type": "string", "description": "The code to import.", "example": "abc_CODE" } }, "additionalProperties": false }, "UnassignedCodeImportRequest": { "required": [ "codes" ], "type": "object", "properties": { "codes": { "type": "array", "items": { "$ref": "#/components/schemas/UnassignedCodeImport" }, "description": "Codes list to import." } }, "additionalProperties": false }, "UpdatePostStatus": { "enum": [ "published", "archived" ], "type": "string" }, "UpdateRewardStatus": { "enum": [ "fulfilled", "pending", "willNotFulfill", "notRedeemed" ], "type": "string" }, "UserAccount": { "type": "object", "properties": { "accountId": { "type": "integer", "format": "int64" }, "uniqueId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "gender": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "mobilePhone": { "type": "string", "nullable": true }, "imageUri": { "type": "string", "nullable": true }, "profileUri": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "websites": { "type": "string", "nullable": true }, "expandedWebsites": { "type": "array", "items": { "$ref": "#/components/schemas/UserUrlDetails" }, "nullable": true }, "stats": { "$ref": "#/components/schemas/AccountStats" }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/AccountSocialPost" }, "nullable": true }, "customer": { "$ref": "#/components/schemas/AccountCustomer" }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/Address" }, "nullable": true }, "removeAndArchive": { "type": "boolean" }, "isFollowing": { "type": "boolean" }, "udf1": { "type": "string", "nullable": true }, "authInfo": { "$ref": "#/components/schemas/Authentication" }, "profileTypeId": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false }, "UserCashReward": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "accountId": { "type": "integer", "format": "int64" }, "ambassadorName": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "rewardTypeId": { "type": "integer", "description": "REWARD_TYPE_CAMPAIGN or REWARD_TYPE_MILESTONE.", "format": "int32" }, "sourceTypeName": { "type": "string", "description": "\"Campaign cash\" or \"Milestone cash\".", "nullable": true }, "sourceName": { "type": "string", "description": "The specific campaign or milestone tier the cash came from.", "nullable": true }, "sourceId": { "type": "integer", "format": "int64", "nullable": true }, "milestoneSeriesId": { "type": "integer", "format": "int64", "nullable": true }, "milestoneSeriesName": { "type": "string", "nullable": true }, "earnedDate": { "type": "string", "format": "date-time", "nullable": true }, "rewardStatusId": { "type": "integer", "format": "int32" }, "rewardStatusName": { "type": "string", "nullable": true }, "rewardAmount": { "type": "number", "format": "double" }, "currencyId": { "type": "integer", "format": "int32", "nullable": true }, "currencyCode": { "type": "string", "nullable": true }, "rewardTemplateId": { "type": "integer", "format": "int64", "nullable": true }, "internalNote": { "type": "string", "description": "Why the brand gave this reward. Carries the explanation for a manual cash reward.", "nullable": true }, "ambassadorNote": { "type": "string", "description": "The note shown to the ambassador, if one was written.", "nullable": true }, "createDate": { "type": "string", "format": "date-time", "nullable": true }, "modifyDate": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "A cash reward earned from completing a campaign or unlocking a milestone tier. Backs the\r\nCash Rewards tab of Payments -> Rewards. Unlike a referral reward these are not derived from\r\nan order, which is why they need their own list rather than a filter on the referral one." }, "UserCashRewardOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/UserCashReward" } }, "additionalProperties": false }, "UserCashRewardPaginatedResult": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserCashReward" }, "description": "The result set", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "additionalProperties": false }, "UserCashRewardPaginatedResultOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/UserCashRewardPaginatedResult" } }, "additionalProperties": false }, "UserCashRewardSummary": { "type": "object", "properties": { "pendingAmount": { "type": "number", "format": "double" }, "approvedUnpaidAmount": { "type": "number", "format": "double" }, "paidAmount": { "type": "number", "format": "double" }, "currencyCount": { "type": "integer", "description": "How many distinct currencies the summed amounts above span. Cash is always minted in the\r\nbrand's configured currency, so this is normally 1 - but a brand that changed its currency\r\nmid-flight leaves older rows behind, and a single summed figure would then be meaningless.\r\nCallers should suppress or qualify the tiles when this exceeds 1.", "format": "int32" } }, "additionalProperties": false, "description": "Summary tiles for the Cash Rewards tab. Deliberately cash-only amounts - these must never be\r\ncombined with a points figure." }, "UserCashRewardSummaryOpenApiResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request succeeded", "example": true }, "message": { "type": "string", "description": "Generally is the error message when the request fails", "nullable": true, "example": null }, "result": { "$ref": "#/components/schemas/UserCashRewardSummary" } }, "additionalProperties": false }, "UserCommunityChannelProgramsPutRequest": { "type": "object", "properties": { "programIds": { "type": "array", "items": { "type": "integer", "format": "int32" }, "nullable": true }, "programIdsAutoAddMembersToChannel": { "type": "array", "items": { "type": "integer", "format": "int32" }, "nullable": true }, "removeParticipantsFrom": { "type": "array", "items": { "type": "integer", "format": "int32" }, "nullable": true } }, "additionalProperties": false }, "UserCustomerOrderMetadata": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "userCustomerOrderId": { "type": "integer", "format": "int64" }, "brandUserId": { "type": "integer", "format": "int64" }, "typeId": { "type": "integer", "format": "int32" }, "value": { "nullable": true }, "createDate": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "UserUrlDetails": { "type": "object", "properties": { "url": { "type": "string", "nullable": true }, "expandedUrl": { "type": "string", "nullable": true }, "displayUrl": { "type": "string", "nullable": true } }, "additionalProperties": false }, "UserWebhookPostRequest": { "type": "object", "properties": { "address": { "type": "string", "description": "Filter webhooks that send POST requests to this URI.", "nullable": true, "example": "`https://my.app.com/webhook/listener`" }, "topic": { "type": "string", "description": "Filter webhooks subscribed to a given topic.", "nullable": true, "example": "'reward/redeemed'" } }, "additionalProperties": false }, "UserWebhookPutRequest": { "type": "object", "properties": { "address": { "type": "string", "description": "Filter webhooks that send POST requests to this URI.", "nullable": true, "example": "`https://my.app.com/webhook/listener`" } }, "additionalProperties": false }, "VisibilityChannelType": { "enum": [ "public", "private", "hidden" ], "type": "string" } }, "securitySchemes": { "Bearer": { "type": "apiKey", "description": "Authorization Header: Bearer {token}", "name": "Authorization", "in": "header" } } }, "security": [ { "Bearer": [ ] } ], "tags": [ { "name": "Events", "description": "Events are generated by specific Roster resources when certain actions are completed, such as the creation of a discount code, the redemption of product rewards, or a new referred order. By requesting events, your app can know when certain actions have occurred in your account.\n

\n The events returned by the Event resource should not be considered to be realtime. Events might not be created until a few seconds after the action occurs. In rare cases, it can take up to a few minutes for some events to appear.\n

\n Events are generated for the following resources: \n
\n
  • Settings
    • Rewards
\n
  • Sales Attribution
    • Attributions
\n
  • Engagement
    • Milestone Rewards
\n

Settings > Rewards events

\n \n \n \n \n \n \n \n \n \n
VerbMessage
redeemedNew automated product reward redeemed.
\n
\n

Sales Attribution > Attributions

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
VerbMessage
createdOrder was attributed to an ambassador as a referred/personal order.
updatedThe referred/personal order attribution was updated.
deletedThe referred/personal order attribution was deleted.
\n
\n

Engagement > Milestone Rewards

\n \n \n \n \n \n \n \n \n \n
VerbMessage
createdAmbassador received a reward for unlocking a milestone.
" }, { "name": "Webhooks", "description": "You can use webhook subscriptions to receive notifications about particular events in your account. After you've subscribed to a webhook topic, your software can execute code immediately after specific events occur instead of having to make API calls periodically to check their status.\n

\n For example, you can rely on webhooks to trigger an action in your software when an ambassador earns a new reward for completing a campaign or unlocking a milestone. By using webhooks, you can make fewer API calls overall, which makes sure that your software is more efficient.\n

\n\t\t\t\t\t\t

Webhook Verification

\n To verify that the webhook was sent from Roster you can calculate a digital signature. \n\t\t\t\t\t\t Each webhook request includes a Base64 encoded X-Signature-Hmac-SHA256 header, which is generated using the most recent private API access token along with the webhook payload.\n\t\t\t\t\t\t
    \n\t\t\t\t\t\t\t
  1. Calculate Base64 encoded HMAC for the webhook payload by using the SHA256 hash function with the most recent private API access token as the secret.
    2. \n\t\t\t\t\t\t\t
  2. Compare the computed value to the value in the X-Signature-Hmac-SHA256. If the HMAC digest and header value match, then the webhook was sent from Roster.
    3. \n\t\t\t\t\t\t
\n

Webhook Event Topics

\n \n \n \n \n \n \n \n \n \n \n \n\t\t\t\t\t\t\t\n \n \n \n \n\t\t\t\t\t\t\t\n \n \n \n \n\t\t\t\t\t\t\t\n \n \n \n \n\t\t\t\t\t\t\t\n \n \n \n \n\t\t\t\t\t\t\t\n \n \n \n \n\t\t\t\t\t\t\t\n \n \n \n \n\t\t\t\t\t\t\t\n \n \n \n \n
TopicDescriptionResource
reward/redeemedOccurs when an automated product reward is redeemed by an ambassador.Reward
referred_order_attribution/createdOccurs when an order is attributed to an ambassador as a referred order.Attribution
referred_order_attribution/updatedOccurs when a referred order attribution is updated (e.g. the order is partially refunded.)Attribution
referred_order_attribution/deletedOccurs when a referred order attribution is deleted (e.g. the order is canceled and commissions have not yet been paid.)Attribution
personal_order_attribution/createdOccurs when an order is attributed to an ambassador as a personal order.Attribution
personal_order_attribution/updatedOccurs when a personal order attribution is updated (e.g. the order is partially refunded.)Attribution
personal_order_attribution/deletedOccurs when a personal order attribution is deleted (e.g. the order is canceled.)Attribution
milestone_reward/createdOccurs when an ambassador receives a reward for unlocking a milestone.Milestone Reward
\n

Webhook Payloads

\n\n
\n \n
\n
\n
\n{\n\t\"eventId\": 16,\n\t\"eventCreateDate\": \"2023-11-20T12:00:00.000\",\n\t\"webhookId\": 4,\n\t\"webhookQueueId\": 6922,\n\t\"data\": {\n\t\t\"reward\": {\n\t\t\t\"order\": {\n\t\t\t\t\"tags\": [\n\t\t\t\t\t\"Roster Reward\"\n\t\t\t\t],\n\t\t\t\t\"orderId\": 203707,\n\t\t\t\t\"externalOrderId\": \"1700484654\",\n\t\t\t\t\"externalOrderNumber\": \"1700484654\",\n\t\t\t\t\"fulfillmentStatus\": null,\n\t\t\t\t\"subtotalPrice\": 0.00,\n                \"totalPrice\": 0.00\n\t\t\t},\n\t\t\t\"source\": \"campaign\",\n\t\t\t\"sourceId\": 54040,\n\t\t\t\"id\": 8427,\n\t\t\t\"ambassador\": {\n\t\t\t\t\"programId\": 4673,\n\t\t\t\t\"contactId\": 1118383,\n\t\t\t\t\"firstName\": \"Bernhard\",\n\t\t\t\t\"lastName\": \"Jacklyn\",\n\t\t\t\t\"emailAddress\": \"b.jacklyn@youremail.com\"\n\t\t\t},\n\t\t\t\"type\": \"automatedProduct\",\n\t\t\t\"status\": \"redeemed\",\n\t\t\t\"statusDate\": \"2023-11-20T12:10:00.00\",\n\t\t\t\"rewardTemplate\": {\n\t\t\t\t\"id\": 6951,\n\t\t\t\t\"name\": \"Product reward\",\n\t\t\t\t\"value\": 0,\n\t\t\t\t\"description\": \"Thanks for participating in the campaign. We're excited to send you some product. Click Redeem to start your order.\",\n\t\t\t\t\"url\": null,\n\t\t\t\t\"images\": [\n\t\t\t\t\t{\n\t\t\t\t\t\t\"fileName\": \"\",\n\t\t\t\t\t\t\"fileUrl\": \"https://cdn.shopify.com/s/files/1/0614/7194/9035/products/moto2.jpg?v=1665657500\",\n\t\t\t\t\t\t\"resourceId\": null\n\t\t\t\t\t}\n\t\t\t\t]\n\t\t\t},\n\t\t\t\"discountCode\": null,\n\t\t\t\"createdAt\": \"2023-11-20T12:10:00.00\",\n\t\t\t\"updatedAt\": \"2023-11-20T12:10:00.00\"\n\t\t},\n\t\t\"additionalAttributes\": {\n\t\t\t\"lineItems\": [\n\t\t\t\t{\n\t\t\t\t\t\"quantity\": 1,\n\t\t\t\t\t\"variantId\": \"43461168103659\"\n\t\t\t\t}\n\t\t\t],\n\t\t\t\"shippingAddress\": {\n\t\t\t\t\"street\": \"1-addr\",\n\t\t\t\t\"street2\": \"2-addr\",\n\t\t\t\t\"city\": \"Mosbach\",\n\t\t\t\t\"province\": \"Berlin\",\n\t\t\t\t\"postalCode\": \"74821\",\n\t\t\t\t\"country\": \"Germany\",\n\t\t\t\t\"firstName\": \"Gotzone\",\n\t\t\t\t\"lastName\": \"Iriney\"\n\t\t\t}\n\t\t}\n\t}\n}\n
\n
\n
\n
\n
\n \n
\n
\n
\n{\n\t\"eventId\": 17,\n\t\"eventCreateDate\": \"2024-01-19T13:04:35.5\",\n\t\"webhookId\": 11,\n\t\"webhookQueueId\": 54909,\n\t\"data\": {\n\t\t\"attribution\": {\n\t\t\t\"attributionId\": 15091,\n\t\t\t\"attributionType\": \"referral\",\n\t\t\t\"attributionMethod\": \"discountCode\",\n\t\t\t\"order\": {\n\t\t\t\t\"externalOrderSource\": \"scriptTag\",\n\t\t\t\t\"externalOrderId\": \"7255718624\",\n\t\t\t\t\"externalOrderNumber\": \"7255718624\",\n\t\t\t\t\"financialStatus\": null,\n\t\t\t\t\"status\": \"created\",\n\t\t\t\t\"fulfillmentStatus\": null,\n\t\t\t\t\"discountCodes\": [\n\t\t\t\t\t\"YC710KSSPV\"\n\t\t\t\t],\n\t\t\t\t\"referralLinkId\": null,\n\t\t\t\t\"currency\": \"CAD\",\n\t\t\t\t\"externalOrderStatusUrl\": null,\n\t\t\t\t\"isNewCustomer\": true,\n\t\t\t\t\"cancelledAt\": null,\n\t\t\t\t\"orderId\": 20211,\n\t\t\t\t\"orderDate\": \"2024-01-19T13:04:09.603\",\n\t\t\t\t\"subtotalPrice\": 152.4,\n\t\t\t\t\"totalPrice\": 165.89\n\t\t\t},\n\t\t\t\"ambassador\": {\n\t\t\t\t\"contactId\": 1138716,\n\t\t\t\t\"firstName\": \"Gotzone\",\n\t\t\t\t\"lastName\": \"Iriney\",\n\t\t\t\t\"emailAddress\": \"g.iriney@getroster.com\"\n\t\t\t},\n\t\t\t\"attributionSource\": \"YC710KSSPV\",\n\t\t\t\"newCustomer\": true,\n\t\t\t\"createdAt\": \"2024-01-19T13:04:16.1\",\n\t\t\t\"updatedAt\": \"2024-01-19T13:04:29.937\"\n\t\t}\n\t}\n}\n
\n
\n
\n
\n
\n \n
\n
\n
\n{\n\t\"eventId\": 17,\n\t\"eventCreateDate\": \"2024-01-19T13:04:35.5\",\n\t\"webhookId\": 11,\n\t\"webhookQueueId\": 54909,\n\t\"data\": {\n\t\t\"attribution\": {\n\t\t\t\"attributionId\": 15091,\n\t\t\t\"attributionType\": \"referral\",\n\t\t\t\"attributionMethod\": \"discountCode\",\n\t\t\t\"order\": {\n\t\t\t\t\"externalOrderSource\": \"scriptTag\",\n\t\t\t\t\"externalOrderId\": \"7255718624\",\n\t\t\t\t\"externalOrderNumber\": \"7255718624\",\n\t\t\t\t\"financialStatus\": null,\n\t\t\t\t\"status\": \"created\",\n\t\t\t\t\"fulfillmentStatus\": null,\n\t\t\t\t\"discountCodes\": [\n\t\t\t\t\t\"YC710KSSPV\"\n\t\t\t\t],\n\t\t\t\t\"referralLinkId\": null,\n\t\t\t\t\"currency\": \"CAD\",\n\t\t\t\t\"externalOrderStatusUrl\": null,\n\t\t\t\t\"isNewCustomer\": true,\n\t\t\t\t\"cancelledAt\": null,\n\t\t\t\t\"orderId\": 20211,\n\t\t\t\t\"orderDate\": \"2024-01-19T13:04:09.603\",\n\t\t\t\t\"subtotalPrice\": 152.4,\n\t\t\t\t\"totalPrice\": 165.89\n\t\t\t},\n\t\t\t\"ambassador\": {\n\t\t\t\t\"contactId\": 1138716,\n\t\t\t\t\"firstName\": \"Gotzone\",\n\t\t\t\t\"lastName\": \"Iriney\",\n\t\t\t\t\"emailAddress\": \"g.iriney@getroster.com\"\n\t\t\t},\n\t\t\t\"attributionSource\": \"YC710KSSPV\",\n\t\t\t\"newCustomer\": true,\n\t\t\t\"createdAt\": \"2024-01-19T13:04:16.1\",\n\t\t\t\"updatedAt\": \"2024-01-19T13:04:29.937\"\n\t\t}\n\t}\n}\n
\n
\n
\n
\n
\n \n
\n
\n
\n{\n\t\"eventId\": 17,\n\t\"eventCreateDate\": \"2024-01-19T13:04:35.5\",\n\t\"webhookId\": 11,\n\t\"webhookQueueId\": 54909,\n\t\"data\": {\n\t\t\"attribution\": {\n\t\t\t\"attributionId\": 15091,\n\t\t\t\"attributionType\": \"referral\",\n\t\t\t\"attributionMethod\": \"discountCode\",\n\t\t\t\"order\": {\n\t\t\t\t\"externalOrderSource\": \"scriptTag\",\n\t\t\t\t\"externalOrderId\": \"7255718624\",\n\t\t\t\t\"externalOrderNumber\": \"7255718624\",\n\t\t\t\t\"financialStatus\": null,\n\t\t\t\t\"status\": \"created\",\n\t\t\t\t\"fulfillmentStatus\": null,\n\t\t\t\t\"discountCodes\": [\n\t\t\t\t\t\"YC710KSSPV\"\n\t\t\t\t],\n\t\t\t\t\"referralLinkId\": null,\n\t\t\t\t\"currency\": \"CAD\",\n\t\t\t\t\"externalOrderStatusUrl\": null,\n\t\t\t\t\"isNewCustomer\": true,\n\t\t\t\t\"cancelledAt\": null,\n\t\t\t\t\"orderId\": 20211,\n\t\t\t\t\"orderDate\": \"2024-01-19T13:04:09.603\",\n\t\t\t\t\"subtotalPrice\": 152.4,\n\t\t\t\t\"totalPrice\": 165.89\n\t\t\t},\n\t\t\t\"ambassador\": {\n\t\t\t\t\"contactId\": 1138716,\n\t\t\t\t\"firstName\": \"Gotzone\",\n\t\t\t\t\"lastName\": \"Iriney\",\n\t\t\t\t\"emailAddress\": \"g.iriney@getroster.com\"\n\t\t\t},\n\t\t\t\"attributionSource\": \"YC710KSSPV\",\n\t\t\t\"newCustomer\": true,\n\t\t\t\"createdAt\": \"2024-01-19T13:04:16.1\",\n\t\t\t\"updatedAt\": \"2024-01-19T13:04:29.937\"\n\t\t}\n\t}\n}\n
\n
\n
\n
\n
\n \n
\n
\n
\n{\n\t\"eventId\": 18,\n\t\"eventCreateDate\": \"2024-01-19T13:04:35.5\",\n\t\"webhookId\": 12,\n\t\"webhookQueueId\": 54909,\n\t\"data\": {\n\t\t\"attribution\": {\n\t\t\t\"attributionId\": 15091,\n\t\t\t\"attributionType\": \"personal\",\n\t\t\t\"attributionMethod\": \"rewardCode\",\n\t\t\t\"order\": {\n\t\t\t\t\"externalOrderSource\": \"scriptTag\",\n\t\t\t\t\"externalOrderId\": \"7255718624\",\n\t\t\t\t\"externalOrderNumber\": \"7255718624\",\n\t\t\t\t\"financialStatus\": null,\n\t\t\t\t\"status\": \"created\",\n\t\t\t\t\"fulfillmentStatus\": null,\n\t\t\t\t\"discountCodes\": [\n\t\t\t\t\t\"YC710KSSPV\"\n\t\t\t\t],\n\t\t\t\t\"referralLinkId\": null,\n\t\t\t\t\"currency\": \"CAD\",\n\t\t\t\t\"externalOrderStatusUrl\": null,\n\t\t\t\t\"isNewCustomer\": true,\n\t\t\t\t\"cancelledAt\": null,\n\t\t\t\t\"orderId\": 20211,\n\t\t\t\t\"orderDate\": \"2024-01-19T13:04:09.603\",\n\t\t\t\t\"subtotalPrice\": 152.4,\n\t\t\t\t\"totalPrice\": 165.89\n\t\t\t},\n\t\t\t\"ambassador\": {\n\t\t\t\t\"contactId\": 1138716,\n\t\t\t\t\"firstName\": \"Gotzone\",\n\t\t\t\t\"lastName\": \"Iriney\",\n\t\t\t\t\"emailAddress\": \"g.iriney@getroster.com\"\n\t\t\t},\n\t\t\t\"attributionSource\": \"YC710KSSPV\",\n\t\t\t\"newCustomer\": true,\n\t\t\t\"createdAt\": \"2024-01-19T13:04:16.1\",\n\t\t\t\"updatedAt\": \"2024-01-19T13:04:29.937\"\n\t\t}\n\t}\n}\n
\n
\n
\n
\n
\n \n
\n
\n
\n{\n\t\"eventId\": 18,\n\t\"eventCreateDate\": \"2024-01-19T13:04:35.5\",\n\t\"webhookId\": 12,\n\t\"webhookQueueId\": 54909,\n\t\"data\": {\n\t\t\"attribution\": {\n\t\t\t\"attributionId\": 15091,\n\t\t\t\"attributionType\": \"personal\",\n\t\t\t\"attributionMethod\": \"rewardCode\",\n\t\t\t\"order\": {\n\t\t\t\t\"externalOrderSource\": \"scriptTag\",\n\t\t\t\t\"externalOrderId\": \"7255718624\",\n\t\t\t\t\"externalOrderNumber\": \"7255718624\",\n\t\t\t\t\"financialStatus\": null,\n\t\t\t\t\"status\": \"created\",\n\t\t\t\t\"fulfillmentStatus\": null,\n\t\t\t\t\"discountCodes\": [\n\t\t\t\t\t\"YC710KSSPV\"\n\t\t\t\t],\n\t\t\t\t\"referralLinkId\": null,\n\t\t\t\t\"currency\": \"CAD\",\n\t\t\t\t\"externalOrderStatusUrl\": null,\n\t\t\t\t\"isNewCustomer\": true,\n\t\t\t\t\"cancelledAt\": null,\n\t\t\t\t\"orderId\": 20211,\n\t\t\t\t\"orderDate\": \"2024-01-19T13:04:09.603\",\n\t\t\t\t\"subtotalPrice\": 152.4,\n\t\t\t\t\"totalPrice\": 165.89\n\t\t\t},\n\t\t\t\"ambassador\": {\n\t\t\t\t\"contactId\": 1138716,\n\t\t\t\t\"firstName\": \"Gotzone\",\n\t\t\t\t\"lastName\": \"Iriney\",\n\t\t\t\t\"emailAddress\": \"g.iriney@getroster.com\"\n\t\t\t},\n\t\t\t\"attributionSource\": \"YC710KSSPV\",\n\t\t\t\"newCustomer\": true,\n\t\t\t\"createdAt\": \"2024-01-19T13:04:16.1\",\n\t\t\t\"updatedAt\": \"2024-01-19T13:04:29.937\"\n\t\t}\n\t}\n}\n
\n
\n
\n
\n
\n \n
\n
\n
\n{\n\t\"eventId\": 18,\n\t\"eventCreateDate\": \"2024-01-19T13:04:35.5\",\n\t\"webhookId\": 12,\n\t\"webhookQueueId\": 54909,\n\t\"data\": {\n\t\t\"attribution\": {\n\t\t\t\"attributionId\": 15091,\n\t\t\t\"attributionType\": \"personal\",\n\t\t\t\"attributionMethod\": \"rewardCode\",\n\t\t\t\"order\": {\n\t\t\t\t\"externalOrderSource\": \"scriptTag\",\n\t\t\t\t\"externalOrderId\": \"7255718624\",\n\t\t\t\t\"externalOrderNumber\": \"7255718624\",\n\t\t\t\t\"financialStatus\": null,\n\t\t\t\t\"status\": \"created\",\n\t\t\t\t\"fulfillmentStatus\": null,\n\t\t\t\t\"discountCodes\": [\n\t\t\t\t\t\"YC710KSSPV\"\n\t\t\t\t],\n\t\t\t\t\"referralLinkId\": null,\n\t\t\t\t\"currency\": \"CAD\",\n\t\t\t\t\"externalOrderStatusUrl\": null,\n\t\t\t\t\"isNewCustomer\": true,\n\t\t\t\t\"cancelledAt\": null,\n\t\t\t\t\"orderId\": 20211,\n\t\t\t\t\"orderDate\": \"2024-01-19T13:04:09.603\",\n\t\t\t\t\"subtotalPrice\": 152.4,\n\t\t\t\t\"totalPrice\": 165.89\n\t\t\t},\n\t\t\t\"ambassador\": {\n\t\t\t\t\"contactId\": 1138716,\n\t\t\t\t\"firstName\": \"Gotzone\",\n\t\t\t\t\"lastName\": \"Iriney\",\n\t\t\t\t\"emailAddress\": \"g.iriney@getroster.com\"\n\t\t\t},\n\t\t\t\"attributionSource\": \"YC710KSSPV\",\n\t\t\t\"newCustomer\": true,\n\t\t\t\"createdAt\": \"2024-01-19T13:04:16.1\",\n\t\t\t\"updatedAt\": \"2024-01-19T13:04:29.937\"\n\t\t}\n\t}\n}\n
\n
\n
\n
\n
\n \n
\n
\n
\n{\n\t\"eventId\": 17,\n\t\"eventCreateDate\": \"2024-01-19T12:44:56.137\",\n\t\"webhookId\": 10,\n\t\"webhookQueueId\": 54906,\n\t\"data\": {\n\t\t\"reward\": {\n\t\t\t\"milestoneSeriesId\": 3742,\n\t\t\t\"iteration\": 1,\n\t\t\t\"milestone\": {\n\t\t\t\t\"milestoneId\": 8363,\n\t\t\t\t\"name\": \"Milestone3\",\n\t\t\t\t\"dateUnlocked\": \"2024-01-19T12:44:54.997\"\n\t\t\t},\n\t\t\t\"address\": null,\n\t\t\t\"id\": 30916,\n\t\t\t\"ambassador\": {\n\t\t\t\t\"programId\": 9712,\n\t\t\t\t\"contactId\": 1138713,\n\t\t\t\t\"firstName\": \"Gotzone\",\n\t\t\t\t\"lastName\": \"Iriney\",\n\t\t\t\t\"emailAddress\": \"g.iriney@getroster.com\"\n\t\t\t},\n\t\t\t\"type\": \"custom\",\n\t\t\t\"status\": \"pending\",\n\t\t\t\"statusDate\": \"2024-01-19T12:44:55.76\",\n\t\t\t\"rewardTemplate\": {\n\t\t\t\t\"id\": 16215,\n\t\t\t\t\"name\": \"Milestone3 Reward Template\",\n\t\t\t\t\"value\": 0.0,\n\t\t\t\t\"description\": \"A custom reward description.\",\n\t\t\t\t\"url\": null,\n\t\t\t\t\"images\": []\n\t\t\t},\n\t\t\t\"discountCode\": null,\n\t\t\t\"order\": null,\n\t\t\t\"createdAt\": \"2024-01-19T12:44:55.76\",\n\t\t\t\"updatedAt\": \"0001-01-01T00:00:00\"\n\t\t}\n\t}\n}\n
\n
\n
\n
\n\n\n" } ], "x-tagGroups": [ { "name": "Community", "tags": [ "Contacts", "ContactProperties", "Programs", "ProgramSettings", "ProgramApplicants", "ProgramAmbassadors", "CommunityProfiles", "Channels", "ChannelParticipants", "Posts", "Comments", "Likes" ] }, { "name": "Engagement", "tags": [ "Campaign", "CampaignRewards", "CampaignParticipants", "MilestoneSeriesRewards", "MilestoneSeriesParticipants" ] }, { "name": "Sales Attribution", "tags": [ "Attribution", "Clicks", "Orders", "ReferralRewards" ] }, { "name": "Settings", "tags": [ "DiscountRules", "DiscountCodes", "RewardTemplates", "Rewards" ] }, { "name": "Events", "tags": [ "Events", "Webhooks" ] } ] }