The Swaarm Conversion API allows Partners to retrieve detailed conversion reports seamlessly. This API utilizes GraphQL, providing a powerful and flexible approach to data retrieval. Access the API over HTTP with the endpoint provided to you, along with your unique partner ID, by your advertiser.
Authentication
Obtaining an Access Token
To authenticate with the Swaarm API, you'll need a Bearer token. Use the following GraphQL mutation to log in and receive your token:
login(input: AuthLoginInput!): AuthResponse!
AuthLoginInput requires your username and password
AuthResponse includes the access token, refresh token, and user information
Type Details:
input AuthLoginInput {
username: String!
password: String!
}
type AuthResponse {
token: AuthToken
authChallenge: AuthChallenge!
user: User
}
type AuthToken {
accessToken: String!
refreshToken: String!
tokenType: String!
expiresIn: Int!
}
enum AuthChallenge {
NONE
NEW_PASSWORD_REQUIRED
}
type User {
id: String!
lastName: String!
firstName: String!
auth0Id: String
email: String!
roles: [Role!]!
permissions: [Permission!]!
status: UserStatus!
createdBy: String
authLogs(first: Int, offset: Int): AuthLogConnection!
settings: UserSettings
expiresAt: LocalDateTime
}
Example Request:
mutation login {
login(input: {
username: "your-username",
password: "your-password"
}) {
authChallenge
token {
accessToken
refreshToken
tokenType
expiresIn
}
user {
id
}
}
}
The request can be sent with any HTTP client, e.g. curl:
curl 'https://your-api-domain.swaarm-clients.com/graphql' \
-H 'accept: */*' \
-H 'content-type: application/json' \
--data-raw $'{"operationName":"Login","variables":{"input":{"password":"your-password","username":"your-username"}},"query":"mutation Login($input: AuthLoginInput\u0021) {\\n login(input: $input) {\\n ...Auth\\n __typename\\n }\\n}\\n\\nfragment Auth on AuthResponse {\\n authChallenge\\n user {\\n id\\n firstName\\n lastName\\n email\\n permissions\\n roles\\n status\\n __typename\\n }\\n token {\\n accessToken\\n expiresIn\\n refreshToken\\n __typename\\n }\\n __typename\\n}"}'
Replace "your-username" and "your-password" with your actual credentials.
Example response:
{
"data": {
"login": {
"authChallenge": "NONE",
"user": {
"id": "247",
"firstName": "Test",
"lastName": "Test",
"email": "test@swaarm.com",
"permissions": [],
"roles": [],
"status": "ACTIVE",
"__typename": "User"
},
"token": {
"accessToken": "your-access-token",
"expiresIn": 86400,
"refreshToken": "your-refresh-token",
"__typename": "AuthToken"
},
"__typename": "AuthResponse"
}
}
}
Refreshing Your Token
After expiration, you can refresh your access token using the following mutation:
refreshToken(input: AuthRefreshTokenInput!): AuthResponse!
Conversion Report
Reports on conversions can be retrieved by sending the following GraphQL query. The HTTP request must contain an Authorization header with a Bearer token obtained in the Authentication step.
The response contains the report data, as well as a URL which can be used for downloading the report in CSV format. The download request must also be authenticated.
partnerConversionReport(publisherId: String!, filters: [PartnerConversionReportFilter!], start: LocalDateTime!, end: LocalDateTime!, fields: [PartnerConversionField!], csvFields: [PartnerConversionField!], first: Int, offset: Int, sort: PartnerConversionReportSort): PartnerConversionReportRowConnection!
What the fields represent:
publisherId: your partner id
filters: a list of filters that allow you to narrow down the report
start, end: the time interval when the report should run
fields: the list of fields that the report should return
csvFields: the list of fields that the CSV version of the report should include
first: limit on the number of rows of the report (default 10000)
offset: indicates how many rows to skip, to be used in combination with first for pagination
sort: defines how the rows are ordered in the report
GraphQL type definitions:
input PartnerConversionReportFilter {
field: PartnerConversionField!
operator: GenericFilterOperator!
values: [String]
}
enum PartnerConversionField {
POSTBACK_ID,
POSTBACK_TIME
OFFER_ID
OFFER_EVENT_ID
PUBLISHER_SUB_ID
PUBLISHER_SUB_SUB_ID
PUBLISHER_SITE
PUBLISHER_PLACEMENT
PUBLISHER_APP_NAME
OFFER_THEY_GET
OFFER_THEY_GET_CURRENCY
OFFER_ORIGINAL_THEY_GET
OFFER_ORIGINAL_CURRENCY
CLICK_PUBLISHER_CLICK_ID
POSTBACK_IMPRESSION_ATTRIBUTION
CLICK_USER_DEVICE_MAKE
CLICK_USER_DEVICE_MODEL
CLICK_USER_DEVICE_OS
CLICK_USER_DEVICE_OS_VERSION
CLICK_TIME
OFFER_NAME
OFFER_EVENT_NAME
PUBLISHER_POSTBACK_URL
PUBLISHER_POSTBACK_HTTP_STATUS_CODE
}
enum GenericFilterOperator {
IN
NOT_IN
BETWEEN_INCLUDING
LOWER_EQUAL
GREATER_EQUAL
IS_EMPTY
IS_NOT_EMPTY
CONTAINS
NOT_CONTAINS
}
input PartnerConversionReportSort{
field: PartnerConversionField!
order: SortOrder!
}
enum SortOrder {
DESC
ASC
}
type PartnerConversionReportRowConnection {
edges: [PartnerConversionReportRowEdge!]
totalCount: Int!,
csvDownloadUrl: String!
}
type PartnerConversionReportRowEdge {
node: PartnerConversionReportRow!
}
type PartnerConversionReportRow {
records: [PartnerConversionReportRecord!]!
}
type PartnerConversionReportRecord {
field: PartnerConversionField!
value: UserProvidedValue
}
type IntValue {
value: Long!
}
type StringValue {
value: String!
}
type StringArrayValue {
value: [String!]!
}
type BooleanValue {
value: Boolean!
}
type FloatValue {
value: Float
}
type DateValue {
value: LocalDateTime!
}
union UserProvidedValue = BooleanValue | IntValue | FloatValue | StringArrayValue | StringValue | DateValue
Example request:
The following request generates a report containing postback time, publisher click id, offer payout, click time and offer id for postbacks that were received on March 25, 2024, where offer id is 28735. The partner id for this query is 137, the ordering is descending by time, and the maximum number of rows is 50.
query Conversions {
conversions: partnerConversionReport(
publisherId: "137"
fields: ["POSTBACK_TIME", "CLICK_PUBLISHER_CLICK_ID", "OFFER_THEY_GET", "CLICK_TIME", "OFFER_ID", "POSTBACK_ID"]
start: "2024-03-25T00:00:00.000+00:00"
end: "2024-03-25T23:59:59.999+00:00"
filters: [
{
field: "OFFER_ID"
operator: "IN"
values: ["28735"]
}
]
first: 50
offset: 0
sort: {
field: "POSTBACK_TIME"
order: "DESC"
}
) {
downloadToken: csvDownloadUrl
totalCount
edges {
node {
records {
field
value {
... on BooleanValue {
boolValue: value
}
... on DateValue {
dateValue: value
}
... on FloatValue {
floatValue: value
}
... on IntValue {
intValue: value
}
... on StringValue {
stringValue: value
}
... on StringArrayValue {
stringArrayValue: value
}
}
}
}
}
}
}
The request can be sent with any HTTP client, e.g. with curl:
curl 'your-api-endpoint' \
-H 'accept: */*' \
-H 'content-type: application/json' \
-H 'authorization: Bearer your-bearer-token' \
--data-raw $'{"operationName":"Conversions","variables":{"csvFields":["POSTBACK_TIME","CLICK_PUBLISHER_CLICK_ID","OFFER_THEY_GET","CLICK_TIME","OFFER_ID"],"end":"2024-03-25T23:59:59.640+00:00","fields":["POSTBACK_TIME","CLICK_PUBLISHER_CLICK_ID","OFFER_THEY_GET","CLICK_TIME","OFFER_ID","POSTBACK_ID"],"filters":[{"field":"OFFER_ID","operator":"IN","values":["28735"]}],"limit":50,"offset":0,"publisherId":"137","sort":{"field":"POSTBACK_TIME","order":"DESC"},"start":"2024-03-25T00:00:00.000+00:00"},"query":"query Conversions($publisherId: String\u0021, $fields: [PartnerConversionField\u0021], $filters: [PartnerConversionReportFilter\u0021], $limit: Int, $offset: Int, $sort: PartnerConversionReportSort, $end: LocalDateTime\u0021, $start: LocalDateTime\u0021) {\\n conversions: partnerConversionReport(\\n publisherId: $publisherId\\n fields: $fields\\n start: $start\\n end: $end\\n filters: $filters\\n first: $limit\\n offset: $offset\\n sort: $sort\\n ) {\\n downloadToken: csvDownloadUrl\\n totalCount\\n edges {\\n node {\\n records {\\n field\\n value {\\n ... on BooleanValue {\\n boolValue: value\\n __typename\\n }\\n ... on DateValue {\\n dateValue: value\\n __typename\\n }\\n ... on FloatValue {\\n floatValue: value\\n __typename\\n }\\n ... on IntValue {\\n intValue: value\\n __typename\\n }\\n ... on StringValue {\\n stringValue: value\\n __typename\\n }\\n ... on StringArrayValue {\\n stringArrayValue: value\\n __typename\\n }\\n __typename\\n }\\n __typename\\n }\\n __typename\\n }\\n __typename\\n }\\n __typename\\n }\\n}"}'
Example response:
{
"data": {
"conversions": {
"downloadToken": "/download/partner-conversion-report/some-download-token",
"totalCount": 2,
"edges": [
{
"node": {
"records": [
{
"field": "POSTBACK_TIME",
"value": {
"dateValue": "2024-03-25T14:43:10.316",
"__typename": "DateValue"
},
"__typename": "PartnerConversionReportRecord"
},
{
"field": "CLICK_PUBLISHER_CLICK_ID",
"value": null,
"__typename": "PartnerConversionReportRecord"
},
{
"field": "OFFER_THEY_GET",
"value": {
"intValue": 150000000,
"__typename": "IntValue"
},
"__typename": "PartnerConversionReportRecord"
},
{
"field": "CLICK_TIME",
"value": {
"dateValue": "2024-03-25T14:42:30.287",
"__typename": "DateValue"
},
"__typename": "PartnerConversionReportRecord"
},
{
"field": "OFFER_ID",
"value": {
"stringValue": "28735",
"__typename": "StringValue"
},
"__typename": "PartnerConversionReportRecord"
},
{
"field": "POSTBACK_ID",
"value": {
"stringValue": "RTYkwbR-Rn4AAAGOdhC1bAAAAQsAAHA_AAAAiQ.1",
"__typename": "StringValue"
},
"__typename": "PartnerConversionReportRecord"
}
],
"__typename": "PartnerConversionReportRow"
},
"__typename": "PartnerConversionReportRowEdge"
},
{
"node": {
"records": [
{
"field": "POSTBACK_TIME",
"value": {
"dateValue": "2024-03-25T14:42:59.098",
"__typename": "DateValue"
},
"__typename": "PartnerConversionReportRecord"
},
{
"field": "CLICK_PUBLISHER_CLICK_ID",
"value": null,
"__typename": "PartnerConversionReportRecord"
},
{
"field": "OFFER_THEY_GET",
"value": {
"intValue": 100000000,
"__typename": "IntValue"
},
"__typename": "PartnerConversionReportRecord"
},
{
"field": "CLICK_TIME",
"value": {
"dateValue": "2024-03-25T14:41:46.173",
"__typename": "DateValue"
},
"__typename": "PartnerConversionReportRecord"
},
{
"field": "OFFER_ID",
"value": {
"stringValue": "28735",
"__typename": "StringValue"
},
"__typename": "PartnerConversionReportRecord"
},
{
"field": "POSTBACK_ID",
"value": {
"stringValue": "Pthf7rAs2PAAAAGOdhCJmgAAAQsAAHA_AAAAiQ.1",
"__typename": "StringValue"
},
"__typename": "PartnerConversionReportRecord"
}
],
"__typename": "PartnerConversionReportRow"
},
"__typename": "PartnerConversionReportRowEdge"
}
],
"__typename": "PartnerConversionReportRowConnection"
}
}
}