Integration API

The Integration API allows trusted secure applications to access the entire marketplace data: all users, listings, transactions, messages, etc. Such trusted applications are for example applications that run in your own backend systems or applications meant to be executed by authorized marketplace operators.

Authentication

Example request:

$ curl -X GET 'https://flex-api.sharetribe.com/v1/integration_api/marketplace/show' \
    -H 'Authorization: bearer ACCESS_TOKEN'

Every call to the Integration API must be made with a valid access token included in the API request. The access token must be provided via Authorization HTTP header in each API request in the form of:

Authorization: bearer ACCESS_TOKEN

API clients can obtain access tokens directly via the Authentication API or use the Sharetribe Flex Integration SDK, which provides convenience methods of handling authentication and tokens. Using the SDK is recommended over direct API access.

Sharetribe Flex Integration SDK

const flexIntegrationSdk = require('sharetribe-integration-sdk');

const integrationSdk = flexIntegrationSdk.createInstance({
  clientId: '<Your Client ID here>',
  clientSecret: '<Your client secret here>'
});

Sharetribe Flex Integration SDK is available at the moment for JavaScript and provides the easiest way to authenticate and use the Integration API.

Revoking the refresh token

integrationSdk.revoke().then(res => {
  console.log("Refresh token revoked.")
});

The Integration SDK is ready for use as soon as it is instantiated, as illustrated in the example on the right. It automatically maintains internally a refresh token, which serves as a session secret. In some cases, you may wish to explicitly revoke the refresh token. You can do so using the .revoke() method of the SDK.

Marketplace

API prefix

/v1/integration_api/marketplace/

Example resource

{
  "data": {
    "id": "16c6a4b8-88ee-429b-835a-6725206cd08c",
    "type": "marketplace",
    "attributes": {
      "name": "My Marketplace",
      "description": "My marketplace"
    }
  }
}

{
  data: {
    id: UUID {uuid: "16c6a4b8-88ee-429b-835a-6725206cd08c"},
    type: "marketplace",
    attributes: {
      name: "My Marketplace",
      description: "My marketplace"
    }
  }
}

The marketplace API resource represents the public data about the marketplace.

marketplace resource format

Attribute	Description
name	(string) The marketplace name.
description	(string) The marketplace description.

Show marketplace

HTTP request

GET /v1/integration_api/marketplace/show

Example request

$ curl 'https://flex-api.sharetribe.com/v1/integration_api/marketplace/show' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

integrationSdk.marketplace.show().then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "16c6a4b8-88ee-429b-835a-6725206cd08c",
    "type": "marketplace",
    "attributes": {
      "name": "My Marketplace",
      "description": "My marketplace"
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "16c6a4b8-88ee-429b-835a-6725206cd08c"},
    type: "marketplace",
    attributes: {
      name: "My Marketplace",
      description: "My marketplace"
    }
  }
}

Get the marketplace details.

Users

API prefix

/v1/integration_api/users/

Example resource

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "user",
    "attributes": {
      "banned": false,
      "deleted": false,
      "createdAt": "2018-03-28T09:12:58.866Z",
      "email": "joe.dunphy@example.com",
      "emailVerified": true,
      "pendingEmail": null,
      "stripeConnected": false,
      "profile": {
        "firstName": "Joe",
        "lastName": "Dunphy",
        "displayName": "Joe D",
        "abbreviatedName": "JD",
        "bio": "Hello, I'm Joe.",
        "publicData": {
          "age": 27
        },
        "protectedData": {
          "phoneNumber": "+1-202-555-0177"
        },
        "privateData": {
          "newsletter": true
        }
      }
    }
  }
}

{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "user",
    attributes: {
      banned: false,
      deleted: false,
      createdAt: new Date("2018-03-28T09:12:58.866Z"),
      email: "joe.dunphy@example.com",
      emailVerified: true,
      pendingEmail: null,
      stripeConnected: false,
      profile: {
        firstName: "Joe",
        lastName: "Dunphy",
        displayName: "Joe D",
        abbreviatedName: "JD",
        bio: "Hello, I'm Joe.",
        publicData: {
          age: 27
        },
        protectedData: {
          phoneNumber: "+1-202-555-0177"
        },
        privateData: {
          newsletter: true
        }
      }
    }
  }
}

The user API resource represents public data about marketplace users.

user resource format

Attribute	Description
banned	(boolean) Flag indicating whether the user is banned. Banned users have all other attributes set to null or false.
deleted	(boolean) Flag indicating whether the user is deleted. Deleted users have all other attributes set to null or false.
createdAt	(string, timestamp) The date and time the user signed up in ISO 8601 format.
email	(string, case insensitive) The user's email address. The email address acts as username.
emailVerified	(boolean) Flag indicating if the user's email address had been verified.
pendingEmail	(string, nullable) If present, the user is in the process of changing their email and have not yet verified the new (pending) address.
stripeConnected	(boolean) Flag indicating if the user has completed creating a Stripe account.
profile.firstName	(string) User's first name.
profile.lastName	(string) User's last name.
profile.displayName	(string) User's chosen display name. Defaults to first name plus initial of last name.
profile.abbreviatedName	(string) Initials of user's first and last names.
profile.bio	(string, nullable) User's bio.
profile.publicData	(object) User's public data. See Extended data for details.
profile.protectedData	(object) User's protected data. See Extended data for details.
profile.privateData	(object) User's private data. See Extended data for details.

user relationships

Relationship	Resource type	Cardinality	Description
marketplace	marketplace	one	The marketplace of the user.
profileImage	image	one	(optional) User's profile image, if any.
stripeAccount	stripeAccount	one	(optional) User's Stripe Account, if any.

Show user

HTTP request

GET /v1/integration_api/users/show

Example request

$ curl 'https://flex-api.sharetribe.com/v1/integration_api/users/show?id=3c073fae-6172-4e75-8b92-f560d58cd47c' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

var userId = new UUID("3c073fae-6172-4e75-8b92-f560d58cd47c");
integrationSdk.users.show({id: userId}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "user",
    "attributes": {
      "banned": false,
      "deleted": false,
      "createdAt": "2018-03-28T09:12:58.866Z",
      "email": "joe.dunphy@example.com",
      "emailVerified": true,
      "pendingEmail": null,
      "stripeConnected": false,
      "profile": {
        "firstName": "Joe",
        "lastName": "Dunphy",
        "displayName": "Joe D",
        "abbreviatedName": "JD",
        "bio": "Hello, I'm Joe.",
        "publicData": {
          "age": 27
        },
        "protectedData": {
          "phoneNumber": "+1-202-555-0177"
        },
        "privateData": {
          "newsletter": true
        }
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "user",
    attributes: {
      banned: false,
      deleted: false,
      createdAt: new Date("2018-03-28T09:12:58.866Z"),
      email: "joe.dunphy@example.com",
      emailVerified: true,
      pendingEmail: null,
      stripeConnected: false,
      profile: {
        firstName: "Joe",
        lastName: "Dunphy",
        displayName: "Joe D",
        abbreviatedName: "JD",
        bio: "Hello, I'm Joe.",
        publicData: {
          age: 27
        },
        protectedData: {
          phoneNumber: "+1-202-555-0177"
        },
        privateData: {
          newsletter: true
        }
      }
    }
  }
}

Get the public details of a single user. You can look up the user by ID or by email address.

Query parameters

Parameter	Description
id	(optional, uuid) The id of the user.
email	(optiona, string) The email address of the user.

Query users

HTTP request

GET /v1/integration_api/users/query

Example request

$ curl 'https://flex-api.sharetribe.com/v1/integration_api/users/query' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

var userId = new UUID("3c073fae-6172-4e75-8b92-f560d58cd47c");
integrationSdk.users.query().then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
      "type": "user",
      "attributes": {
        "banned": false,
        "deleted": false,
        "createdAt": "2018-04-17T06:54:38.498Z",
        "email": "joe.dunphy@example.com",
        "emailVerified": true,
        "pendingEmail": null,
        "stripeConnected": false,
        "profile": {
          "firstName": "Joe",
          "lastName": "Dunphy",
          "displayName": "Joe D",
          "abbreviatedName": "JD",
          "bio": "Hello, I'm Joe. Some people call me Joe \"Modern\" D.\n\nAnd just so that you wouldn't think that's too short of an introduction, here a bit more about me:\n\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
          "publicData": {
            "hobbies": [
              "pizza",
              "gym"
            ]
          },
          "protectedData": {
            "phoneNumber": "+1-202-555-0177"
          },
          "privateData": {
            "keyCode": "1234",
            "moarStuff": {
              "stuff": {
                "first": 1,
                "second": 2
              }
            }
          }
        }
      }
    },
    {...},
    {...}
  ],
  "meta": {
    "totalItems": 3,
    "totalPages": 1,
    "page": 1,
    "perPage": 100
  }
}

// res.data
{
  data: [
    {
      id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
      type: "user",
      attributes: {
        banned: false,
        deleted: false,
        createdAt: new Date("2018-03-28T09:12:58.866Z"),
        email: "joe.dunphy@example.com",
        emailVerified: true,
        pendingEmail: null,
        stripeConnected: false,
        profile: {
          firstName: "Joe",
          lastName: "Dunphy",
          displayName: "Joe D",
          abbreviatedName: "JD",
          bio: "Hello, I'm Joe.",
          publicData: {
            age: 27
          },
          protectedData: {
            phoneNumber: "+1-202-555-0177"
          },
          privateData: {
            newsletter: true
          }
        }
      }
    },
    {...},
    {...}
  ],
  meta: {
    totalItems: 3,
    totalPages: 1,
    page: 1,
    perPage: 100
  }
}

Query all users of a marketplace. Results are sorted by users' createdAt time in descending order (i.e. most recent users are returned first).

Query parameters

Parameter	Description
createdAtStart	(timestamp, optiona) Filter users by createdAt time. Only users created on or after the given time are returned. The timestamp must be in ISO 8601 format.
createdAtEnd	(timestamp, optiona) Filter users by createdAt time. Only users created before the given time are returned. The timestamp must be in ISO 8601 format.

Stripe Account

API prefix

/v1/integration_api/stripe_account/

Example resource

{
  "data": {
    "id": "cb5e8305-67f0-4d04-a081-954411eaf6b9",
    "type": "stripeAccount",
    "attributes": {
      "stripeAccountId": "acct_1EHoPgDktN4RYwdG"
    }
  }
}

{
  data: {
    id: UUID {uuid: "cb5e8305-67f0-4d04-a081-954411eaf6b9"},
    type: "stripeAccount",
    attributes: {
      stripeAccountId: "acct_1EHoPgDktN4RYwdG"
    }
  }
}

The stripeAccount resource type represents details about the Stripe account of a user.

Stripe Accounts are currently accessible only via the stripeAccount relationship of user resources.

stripeAccount resource format

Attribute	Description
stripeAccountId	(string) Stripe's own ID for the Stripe Account.

Listings

API prefix

/v1/integration_api/listings/

Example resource

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "listing",
    "attributes": {
      "description": "7-speed Hybrid",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "published",
      "title": "Peugeot eT101",
      "availabilityPlan": {
        "type": "availability-plan/day",
        "entries": [
          {
            "dayOfWeek": "mon",
            "seats": 1
          },
          {
            "dayOfWeek": "tue",
            "seats": 0
          },
          {
            "dayOfWeek": "fri",
            "seats": 4
          }
        ]
      },
      "privateData": {
        "externalServiceId": "abcd-service-id-1234"
      },
      "publicData": {
        "address": {
          "city": "New York",
          "country": "USA",
          "state": "NY",
          "street": "230 Hamilton Ave"
        },
        "category": "road",
        "gears": 22,
        "rules": "This is a nice, bike! Please, be careful with it."
      },
      "metadata": {
        "promoted": true
      },
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    }
  }
}

{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "listing",
    attributes: {
      description: "7-speed Hybrid",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "published",
      title: "Peugeot eT101",
      availabilityPlan: {
        type: "availability-plan/day",
        entries: [
          {
            dayOfWeek: "mon",
            seats: 1
          },
          {
            dayOfWeek: "tue",
            seats: 0
          },
          {
            dayOfWeek: "fri",
            seats: 7
          }
        ]
      },
      privateData: {
        externalServiceId: "abcd-service-id-1234"
      },
      publicData: {
        address: {
          city: "New York",
          country: "USA",
          state: "NY",
          street: "230 Hamilton Ave"
        },
        category: "road",
        gears: 22,
        rules: "This is a nice, bike! Please, be careful with it."
      },
      metadata: {
        promoted: true
      },
      price: Money {amount: 1590, currency: "USD"}
    }
  }
}

The listing API resource type represents public information about listings in the marketplace.

listing resource format

Attribute	Description
title	(string) Listing's title.
description	(string) Listing's description.
geolocation	(object, location) Latitude (lat) and longitude (lng) of the listing's location.
createdAt	(string, timestamp) The date and time when the listing was created in ISO 8601 format.
price	(object, money) Listing's unit price. currency is the currency code and amount is integer representing amount in the currency's minor unit (e.g. cents for USD).
availabilityPlan	(object) Listing's availability plan. See listing availability plan.
publicData	(object) Listing's public data. See Extended data.
privateData	(object) Listing's private data. See Extended data.
metadata	(object) Listing's public metadata. See Extended data.
state	(string) The listing's current state. See Listing states.
deleted	(boolean) Flag indicating whether the listing has been deleted. If true, all other attributes of the listing will be returned as default values (false for booleans and null for all else).

listing states

A listing resource type may be in one of the following states:

State	Description
draft	Listing is in draft state and has not been published yet. Listings that are in draft state are never returned by the public /listings queries in the Marketplace API.
pendingApproval	Listing is pending operator approval. Newly created listings have this state, when the marketplace has the listing approval feature enabled. Listings that are pending approval are never returned by the public /listings queries in the Marketplace API.
published	Listing is published and discoverable via the /listings/query endpoint of the Marketplace API.
closed	A published listing can be closed by its author or a marketplace operator. Closed listings are not returned in search results or public listing queries in the Marketplace API and new transactions can not be initiated with them, but they can still be accessed as own listings or via the listing ID, or when related to another known resource (such as transaction). The intention of closing a listing is not to delete it, but to stop advertising it. A closed listing can be reopened, which sets it in published state again.

listing availability plan

The listing resource's availabilityPlan attribute contains the type and, in case of time-based availability plans, the timezone of the listing's availability plan.

Attribute	Description
type	(string) Availability plan type. Possible types are availability-plan/day for day-based availability and availability-plan/time for time-based availability.
timezone	(string) Only for the availability-plan/time type. Time zone in which the plan is set. Supports time zone names from the TZ time zone database, for example "Europe/Berlin". See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.
entries	(array) List of zero or more availability entries for the plan.
entries.*.dayOfWeek	(string) An abbreviated day of week: mon, tue, wed, thu, fri, sat or sun.
entries.*.seats	(number) An integer number of available seats for the given day of week. The number of seats indicate how many times a given date can be booked. Setting seats to 0 means that the entry is unavailable for bookings.
entries.*.startTime	(string) Only for the availability-plan/time type. Start time for the availability slot in hh:mm format so that the number of minutes is a multiple of 5.
entries.*.endTime	(string) Only for the availability-plan/time type. End time for the availability slot in hh:mm format so that the number of minutes is a multiple of 5. 00:00 can be used to express midnight.

Listings without an availability plan are interpreted to have a day-based plan with 1 seat available for each day of the week.

listing relationships

Relationship	Resource type	Cardinality	Description
marketplace	marketplace	one	The marketplace of the user.
author	user	one	The marketplace user, to whom the listing belongs. Supported nested relationships: author.profileImage.
images	image	many	(optional) The ordered list of listing images, if any.

Show listing

HTTP request

GET /v1/integration_api/listings/show

Example request

$ curl 'https://flex-api.sharetribe.com/v1/integration_api/listings/show?id=c6ff7190-bdf7-47a0-8a2b-e3136e74334f' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

var listingId = new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f");
integrationSdk.listings.show({id: listingId}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "listing",
    "attributes": {
      "description": "7-speed Hybrid",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "published",
      "title": "Peugeot eT101",
      "availabilityPlan": {
        "type": "availability-plan/day",
        "entries": [
          {
            "dayOfWeek": "mon",
            "seats": 3
          },
          {
            "dayOfWeek": "fri",
            "seats": 1
          }
        ]
      },
      "privateData": {
        "externalServiceId": "abcd-service-id-1234"
      },
      "publicData": {
        "address": {
          "city": "New York",
          "country": "USA",
          "state": "NY",
          "street": "230 Hamilton Ave"
        },
        "category": "road",
        "gears": 22,
        "rules": "This is a nice, bike! Please, be careful with it."
      },
      "metadata": {
        "promoted": true
      },
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    }
  }
}

{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "listing",
    attributes: {
      description: "7-speed Hybrid",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "published",
      title: "Peugeot eT101",
      availabilityPlan: {
        type: "availability-plan/day",
        entries: [
          {
            dayOfWeek: "mon",
            seats: 3
          },
          {
            dayOfWeek: "fri",
            seats: 1
          }
        ]
      },
      privateData: {
        externalServiceId: "abcd-service-id-1234"
      },
      publicData: {
        address: {
          city: "New York",
          country: "USA",
          state: "NY",
          street: "230 Hamilton Ave"
        },
        category: "road",
        gears: 22,
        rules: "This is a nice, bike! Please, be careful with it."
      },
      metadata: {
        promoted: true
      },
      price: Money {amount: 1590, currency: "USD"}
    }
  }
}

Query the public details of a given listing.

Query parameters

Parameter	Description
id	The ID of the listing.

Query listings

HTTP request

GET /v1/integration_api/listings/query

Example request

# Search all listings, ordered by distance from given location,
# matching only listings with `publicData.gears` less than 23
# and price amount between 14.00 and 16.00.
$ curl 'https://flex-api.sharetribe.com/v1/integration_api/listings/query?origin=40.00,-74.00&price=1400,1600&pub_gears=,23' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

// Search all listings, ordered by distance from given location,
// matching only listings with `publicData.gears` less than 23
// and price amount between 14.00 and 16.00.
var origin = new LatLng(40.0, -74.0);
integrationSdk.listings.query({
  origin: origin,
  price: "1400,1600",
  pub_gears: ",23"
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
      "type": "listing",
      "attributes": {
        "description": "7-speed Hybrid",
        "deleted": false,
        "geolocation": {
          "lat": 40.64542,
          "lng": -74.08508
        },
        "createdAt": "2018-03-23T08:40:24.443Z",
        "state": "published",
        "title": "Peugeot eT101",
        "availabilityPlan": {
          "type": "availability-plan/day",
          "entries": [
            {
              "dayOfWeek": "mon",
              "seats": 3
            },
            {
              "dayOfWeek": "fri",
              "seats": 1
            }
          ]
        },
        "privateData": {
          "externalServiceId": "abcd-service-id-1234"
        },
        "publicData": {
          "address": {
            "city": "New York",
            "country": "USA",
            "state": "NY",
            "street": "230 Hamilton Ave"
          },
          "category": "road",
          "gears": 22,
          "rules": "This is a nice, bike! Please, be careful with it."
        },
        "metadata": {
          "promoted": true
        },
        "price": {
          "amount": 1590,
          "currency": "USD"
        }
      }
    },
    {...},
    {...}
  ],
  "meta": {
    "totalItems": 1014,
    "totalPages": 11,
    "page": 1,
    "perPage": 100
  }
}

{
  data: [
    {
      id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
      type: "listing",
      attributes: {
        description: "7-speed Hybrid",
        deleted: false,
        geolocation: LatLng {lat: 40.64542, lng: -74.08508},
        createdAt: new Date("2018-03-23T08:40:24.443Z"),
        state: "published",
        title: "Peugeot eT101",
        availabilityPlan: {
          type: "availability-plan/day",
          entries: [
            {
              dayOfWeek: "mon",
              seats: 3
            },
            {
              dayOfWeek: "fri",
              seats: 1
            }
          ]
        },
        privateData: {
          externalServiceId: "abcd-service-id-1234"
        },
        publicData: {
          address: {
            city: "New York",
            country: "USA",
            state: "NY",
            street: "230 Hamilton Ave"
          },
          category: "road",
          gears: 22,
          rules: "This is a nice, bike! Please, be careful with it."
        },
        metadata: {
          promoted: true
        },
        price: Money {amount: 1590, currency: "USD"}
      }
    },
    {...},
    {...}
  ],
  meta: {
    totalItems: 1014,
    totalPages: 11,
    page: 1,
    perPage: 100
  }
}

Query published marketplace listings. Returns 0 or more results. Unless origin query parameter is given, results are sorted by listing createdAt time in descending order (i.e. newest listings are returned first).

This query does not return listings that are in the closed state.

Query parameters

Parameter	Description
authorId	(uuid, optional) Match only listings belonging to given user ID.
states	(comma separated list of strings, optional) List of states to filter the results by. Only listings in one of the given states are returned.
createdAtStart	(timestamp, optiona) Filter listings by createdAt time. Only listings created on or after the given time are returned. The timestamp must be in ISON 8601 format.
createdAtEnd	(timestamp, optiona) Filter listings by createdAt time. Only listings created before the given time are returned. The timestamp must be in ISON 8601 format.
keywords	(string, optional) Narrow down and sort search results based on given keywords. The keywords are matched against listing title, description and optionally also specific publidData fields with type text defined in the listing public data schema of a marketplace. Can not be combined with the origin parameter.
origin	(coordinates, optional) Search listings, based on given location. The location is given as comma-separated tuple of latitude and longitude values (e.g. 40.12,-70.3345). The listings in the query result are sorted by distance from the given origin. Can not be combined with the keywords parameter.
bounds	(bounding box coordinates, optional) Match only listings within a bounding box. The bounding box is given as comma-separated list of four coordinate values: NE lat, NE, lng, SW lat and SW lng. E.g. 43.0,-73.0,40.0,-77.0.
price	(integer or integer range, optional) Match only listings with price amount within given range. The amounts must be given as integers in the currency's minor unit (e.g. cents for USD). The currency of the listing price has no effect on the query. See below for range syntax.
start	(timestamp, optional) Start time of the availability interval to match listings against in ISO 8601 format. The start time must be between one day in the past and 365 days in the future. If omitted, the listings' availability data is ignored in the query. Only supported for querying listings with day-based availability plans.
end	(timestamp, optional) End time of the availability interval to match listings against (exclusive) in ISO 8601 format. The end time must be after the start time and must be at most 365 days in the future or at most 90 days from the start time (whichever comes sooner). Only supported for querying listings with day-based availability plans.
seats	(integer) The number of seats a listing must have available at minimum on the given interval to to match the search criteria.
availability	(string, optional) Accepts values: full OR partial. full means the matched listing must be available for the entirety of the given availability interval. partial means the matched listings must have some availability in the given interval. Default value is: full.
pub_*	(optional) Query listings by publicData attribute(s). See below.
meta_*	(optional) Query listings by metadata attribute(s). See below.

price range can be specified as:

Query syntax	Description
price=VALUE	Match listings that have price amount exactly equal to VALUE.
price=START,END	Match listings that have price amount greater than or equal to START and less than END.
price=START,	Match listings that have price amount greater than or equal to START.
price=,END	Match listings that have price amount less than END.

Queries for publicData and metadata attributes can be done only when extended data schema is defined for the attribute. Only top-level extended data attributes may have schema and are queriable, even though the extended data can be deeply nested. The supported schema types and query semantics are given below:

Schema type	Schema cardinality	Query syntax	Description
enum	one	pub_ATTRIBUTE_KEY=VALUE1,[VALUE2[,...]]	Match listings that have any of the given values as the exact value of ATTRIBUTE_KEY (i.e. OR semantics).
enum	many	pub_ATTRIBUTE_KEY=has_all:VALUE1[,VALUE2[,...]]	Match listings that have all given values for the given multi-enum ATTRIBUTE_KEY (i.e. AND semantics).
enum	many	pub_ATTRIBUTE_KEY=VALUE1[,VALUE2[,...]]	Same as has_all:, we use AND semantics by default.
enum	many	pub_ATTRIBUTE_KEY=has_any:VALUE1[,VALUE2[,...]]	Match listings that have any of the given values for the multi-enum ATTRIBUTE_KEY (i.e. OR semantics).
long	one	pub_ATTRIBUTE_KEY=VALUE	Match listings that have a value of ATTRIBUTE_KEY that is exactly equal toVALUE.
long	one	pub_ATTRIBUTE_KEY=START,END	Match listings that have a value of ATTRIBUTE_KEY that is greater than or equal to START and less than END.
long	one	pub_ATTRIBUTE_KEY=START,	Match listings that have a value of ATTRIBUTE_KEY that is greater than or equal to START.
long	one	pub_ATTRIBUTE_KEY=,END	Match listings that have a value of ATTRIBUTE_KEY that is less than END.
boolean	one	pub_ATTRIBUTE_KEY=VALUE	Match listings that have a value of ATTRIBUTE_KEY that is equal to VALUE.
text	one	keywords=KEYWORDS	Match and sort listings that have a string from KEYWORDS in listing title, description or extended data attributes with type text.

Images

API prefix

/v1/integration_api/images

Example resource

{
  "data": {
    "id": "5a8f34f6-202c-4916-af7a-53d56004e872",
    "type": "image",
    "attributes": {
      "variants": {
        "default": {
          "name": "default",
          "width": 720,
          "height": 540,
          "url": "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872"
        },
        "landscape-crop": {
          "name": "landscape-crop",
          "width": 800,
          "height": 600,
          "url": "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872?v=landscape-crop"
        },
        "landscape-crop2x": {
          "name": "landscape-crop2x",
          "width": 1600,
          "height": 1200,
          "url": "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872?v=landscape-crop2x"
        }
      }
    }
  }
}

{
  data: {
    id: UUID {uuid: "5a8f34f6-202c-4916-af7a-53d56004e872"},
    type: "image",
    attributes: {
      variants: {
        default: {
          name: "default",
          width: 720,
          height: 540,
          url: "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872"
        },
        "landscape-crop": {
          name: "landscape-crop",
          width: 800,
          height: 600,
          url: "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872?v=landscape-crop"
        },
        "landscape-crop2x": {
          name: "landscape-crop2x",
          width: 1600,
          height: 1200,
          url: "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872?v=landscape-crop2x"
        }
      }
    }
  }
}

The image resource represents user profile and listing images.

image resource format

Attribute	Description
variants	(object) Object containing image variant information. Keys are variant names and values are objects representing the variant.
variants.*.width	(number) The actual width of the image in pixels after the transformation corresponding to the variant.
variants.*.height	(number) The actual height of the image in pixels after the transformation corresponding to the variant.
variants.*.url	(string) The public URL for the image variant. Always use the returned URL exactly as returned by the API. Do not attempt to manually construct an image URL.
variants.*.name	(string) The variant name. Same as the key.

The following image variants are available for profile and listing images:

Variant	Transformation	Width	Height
default	fit, clip	750px	750px
landscape-crop	fit, crop	400px	267px
landscape-crop2x	fit, crop	800px	533px
landscape-crop4x	fit, crop	1600px	1066px
landscape-crop6x	fit, crop	2400px	1602px
scaled-small	fit, clip	320px	320px
scaled-medium	fit, clip	750px	750px
scaled-large	fit, clip	1024px	1024px
scaled-xlarge	fit, clip	2400px	2400px
square-small	fit, crop	240px	240px
square-small2x	fit, crop	480px	480px
facebook	fit, crop	1200px	630px
twitter	fit, crop	600px	314px

Transformation	Description
fit, clip	Resizes the image to fit within the width and height dimensions preserving the image aspect ratio without cropping. The actual image smaller side will vary depending on the image aspect ratio.
fit, crop	Resizes the image to fit both dimensions and crops away the excess. Uses edge detection algorithm for determining which portion of the image to center the crop on.

Transactions

API prefix

/v1/integration_api/transactions

Example resource

{
  "data": {
    "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
    "type": "transaction",
    "attributes": {
      "createdAt": "2018-03-27T12:30:02.000Z",
      "processName": "preauth-with-nightly-booking",
      "processVersion": 3,
      "lastTransition": "transition/request",
      "lastTransitionedAt": "2018-03-27T12:30:03.100Z",
      "payinTotal": {
        "amount": 6360,
        "currency": "USD"
      },
      "payoutTotal": {
        "amount": 5724,
        "currency": "USD"
      },
      "lineItems": [
        {
          "code": "line-item/day",
          "quantity": 4,
          "units": 2,
          "seats": 2,
          "reversal": false,
          "unitPrice": {
            "amount": 1590,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": 6360,
            "currency": "USD"
          },
          "includeFor": [
            "customer",
            "provider"
          ]
        },
        {
          "code": "line-item/provider-commission",
          "percentage": -10.0,
          "reversal": false,
          "unitPrice": {
            "amount": 6360,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": -636,
            "currency": "USD"
          },
          "includeFor": [
            "provider"
          ]
        }
      ],
      "protectedData": {
        "phoneNumber": "+1-202-555-5555"
      },
      "transitions": [
        {
          "transition": "transition/request",
          "createdAt": "2018-03-27T12:30:03.100Z",
          "by": "customer"
        }
      ]
    }
  }
}

{
  data: {
    id: UUID {uuid: "ef98e897-5b81-49a5-aca6-01d9759df075"},
    type: "transaction",
    attributes: {
      createdAt: new Date("2018-03-27T12:30:02.000Z"),
      processName: "preauth-with-nightly-booking",
      processVersion: 3,
      lastTransition: "transition/request",
      lastTransitionedAt: new Date("2018-03-27T12:30:03.100Z"),
      payinTotal: {
        amount: 6360,
        currency: "USD"
      },
      payoutTotal: {
        amount: 5724,
        currency: "USD"
      },
      lineItems: [
        {
          code: "line-item/day",
          quantity: 4,
          units: 2,
          seats: 2,
          reversal: false,
          unitPrice: {
            amount: 1590,
            currency: "USD"
          },
          lineTotal: {
            amount: 6360,
            currency: "USD"
          },
          includeFor: [
            "customer",
            "provider"
          ]
        },
        {
          code: "line-item/provider-commission",
          percentage: -10.0,
          reversal: false,
          unitPrice: {
            amount: 6360,
            currency: "USD"
          },
          lineTotal: {
            amount: -636,
            currency: "USD"
          },
          includeFor: [
            "provider"
          ]
        }
      ],
      protectedData: {
        phoneNumber: "+1-202-555-5555"
      },
      transitions: [
        {
          transition: "transition/request",
          createdAt: new Date("2018-03-27T12:30:03.100Z"),
          by: "customer"
        }
      ]
    }
  }
}

The transaction API resource type represents information about transactions.

transaction resource format

Attribute	Description
createdAt	(string) The date and time when the transaction was initiated in ISO 8601 format.
processName	(string) The (unique) name for the process this transaction uses
processVersion	(number) The version of the transaction process
lastTransition	(string, timestamp) The name of the last transition that happened in the transaction. See Transaction process.
lastTransitionedAt	(string, timestamp) The date and time when the last transition in the transaction occurred, in ISO 8601 format.
lineItems	(array) Array of line item objects, that represent the pricing breakdown of the transaction.
lineItems.*.code	(string) The line item code. See the table below for list of possible codes.
lineItems.*.unitPrice	(object, money) Unit price.
lineItems.*.quantity	(number, optional) When applicable, the complete number of booked units that the line item represents. When units and seats are provided quantity always equals to units x seats. Can be non-integer or negative number.
lineItems.*.units	(number, optional) When applicable, the number of units that the line item represents. Multiplying units with seats equals quantity. Can be non-integer or negative number.
lineItems.*.seats	(number, optional) When applicable, the number of seats that the line item represents. Multiplying seats with units equals quantity. Must be a positive integer.
lineItems.*.percentage	(number, optional) When applicable, the percentage value that the line item represents. Can be negative. E.g. 5.0 (5%).
lineItems.*.lineTotal	(object, money) The line item total value. amount can be negative. The line total is always equal to either quantity x unitPrice or percentage x unitPrice / 100.
lineItems.*.reversal	(boolean) Flag indicating whether the line item is a reversal of another line item. Reversal are added when there has been a reversal (typically a refund).
lineItems.*.includedFor	(array) Array of strings, indicating whether the line item applies to customer, provider or both. For instance, a commission that the provider pays does not affect the total from the point of view of the customer.
payinTotal	(object, money) The total monetary amount of the payin (i.e. the amount paid by the customer). This amount is the sum total of all line items that apply to the customer (i.e. have customer in their includedFor lists).
payoutTotal	(object, money) The total monetary amount of the payout (i.e. the amoun paid to the provider). This amount is the sum total of all line items that apply to the provider (i.e. have provider in their includedFor lists).
protectedData	(object) Transaction's protected data. See Extended data for details.
transitions	(array) The transaction's transition history - list of transition objects, in chronological order.
transitions.*.transition	(string) The name of the transition. See Transaction process.
transitions.*.createdAt	(string, timestamp) The date and time when the transition occurred in ISO 8601 format.
transitions.*.by	(string) The actor that performed the transition. One of customer, provider, operator or system.

The following table lists all currently available codes. Depending on your transaction process, the codes that your marketplace uses is a subset of the ones listed below.

Line item code	Description
line-item/day	Line item representing the price of daily booking for given number of days.
line-item/night	Line item representing the price of nightly booking for given number of nights.
line-item/units	Line item representing the price of units for given quantity.
line-item/units1	Line item representing the price of units type "1" for given quantity in a two unit transaction.
line-item/units2	Line item representing the price of units type "2" for given quantity in a two unit transaction.
line-item/negotiation	Line item representing negotiated change to the total price.
line-item/provider-commission	Line item representing commission that is paid by the provider.
line-item/customer-commission	Line item representing commission that is paid by the customer.
line-item/provider-fixed-commission	Line item representing a fixed commission that is paid by the provider.
line-item/customer-fixed-commission	Line item representing a fixed commission that is paid by the customer.
line-item/<custom code>	With custom pricing the line item code can be any string with line-item/ prefix and a maximum length of 64 characters.

transaction relationships

Relationship	Resource type	Cardinality	Description
marketplace	marketplace	one	The marketplace of the transaction.
listing	listing	one	The listing that the transaction is about. Supported nested relationships: listing.images.
provider	user	one	The user who is author of the listing that the transaction is about. Supported nested relationships: provider.profileImage.
customer	user	one	The customer who initiated the transaction. Supported nested relationships: customer.profileImage.
booking	booking	one	(optional) The booking created by the transaction, if any.
reviews	review	many	(optional) The reviews of the parties in the transaction, if any. Supported nested relationships: reviews.author, reviews.author.profileImage, reviews.subject, reviews.subject.profileImage.
messages	message	many	(optional) The messages that the parties have sent to one another as part of the transaction, if any. Note that there may be large number of messages. It is therefore recommended to use limits when including this relationship. Alternatively, use /messages/query API endpoint. Supported nested relationships: messages.sender, messages.sender.profileImage.

Show transaction

HTTP request

GET /v1/integration_api/transactions/show

Example request

$ curl 'https://flex-api.sharetribe.com/v1/integration_api/transactions/show?id=ef98e897-5b81-49a5-aca6-01d9759df075' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

integrationSdk.transactions.show({
  id: new UUID("ef98e897-5b81-49a5-aca6-01d9759df075")
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
    "type": "transaction",
    "attributes": {
      "createdAt": "2018-03-27T12:30:02.000Z",
      "processName": "preauth-with-nightly-booking",
      "processVersion": 3,
      "lastTransition": "transition/request",
      "lastTransitionedAt": "2018-03-27T12:30:03.100Z",
      "payinTotal": {
        "amount": 6360,
        "currency": "USD"
      },
      "payoutTotal": {
        "amount": 5724,
        "currency": "USD"
      },
      "lineItems": [
        {
          "code": "line-item/day",
          "quantity": 4,
          "units": 2,
          "seats": 2,
          "reversal": false,
          "unitPrice": {
            "amount": 1590,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": 6360,
            "currency": "USD"
          },
          "includeFor": [
            "customer",
            "provider"
          ]
        },
        {
          "code": "line-item/provider-commission",
          "percentage": -10.0,
          "reversal": false,
          "unitPrice": {
            "amount": 6360,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": -636,
            "currency": "USD"
          },
          "includeFor": [
            "provider"
          ]
        }
      ],
      "protectedData": {},
      "transitions": [
        {
          "transition": "transition/request",
          "createdAt": "2018-03-27T12:30:03.100Z",
          "by": "customer"
        }
      ]
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "ef98e897-5b81-49a5-aca6-01d9759df075"},
    type: "transaction",
    attributes: {
      createdAt: new Date("2018-03-27T12:30:02.000Z"),
      processName: "preauth-with-nightly-booking",
      processVersion: 3,
      lastTransition: "transition/request",
      lastTransitionedAt: new Date("2018-03-27T12:30:03.100Z"),
      payinTotal: {
        amount: 6360,
        currency: "USD"
      },
      payoutTotal: {
        amount: 5724,
        currency: "USD"
      },
      lineItems: [
        {
          code: "line-item/day",
          quantity: 4,
          unit: 2,
          seats: 2,
          reversal: false,
          unitPrice: {
            amount: 1590,
            currency: "USD"
          },
          lineTotal: {
            amount: 6360,
            currency: "USD"
          },
          includeFor: [
            "customer",
            "provider"
          ]
        },
        {
          code: "line-item/provider-commission",
          percentage: -10.0,
          reversal: false,
          unitPrice: {
            amount: 6360,
            currency: "USD"
          },
          lineTotal: {
            amount: -636,
            currency: "USD"
          },
          includeFor: [
            "provider"
          ]
        }
      ],
      protectedData: {},
      transitions: [
        {
          transition: "transition/request",
          createdAt: new Date("2018-03-27T12:30:03.100Z"),
          by: "customer"
        }
      ]
    }
  }
}

Query returning data about given transaction.

Query parameters

Parameter	Description
id	The ID of the transaction.

Query transactions

HTTP request

GET /v1/integration_api/transactions/query

Example request

# Query transactions where the user is provider and the last transition is 'transition/request'
$ curl 'https://flex-api.sharetribe.com/v1/integration_api/transactions/query' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

// Query transactions where the user is provider and the last transition is 'transition/request'
integrationSdk.transactions.query().then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
      "type": "transaction",
      "attributes": {
        "createdAt": "2018-03-27T12:30:02.000Z",
        "processName": "preauth-with-nightly-booking",
        "processVersion": 3,
        "lastTransition": "transition/request",
        "lastTransitionedAt": "2018-03-27T12:30:03.100Z",
        "payinTotal": {
          "amount": 6360,
          "currency": "USD"
        },
        "payoutTotal": {
          "amount": 5724,
          "currency": "USD"
        },
        "lineItems": [
          {
            "code": "line-item/day",
            "quantity": 4,
            "units": 2,
            "seats": 2,
            "reversal": false,
            "unitPrice": {
              "amount": 1590,
              "currency": "USD"
            },
            "lineTotal": {
              "amount": 6360,
              "currency": "USD"
            },
            "includeFor": [
              "customer",
              "provider"
            ]
          },
          {
            "code": "line-item/provider-commission",
            "percentage": -10.0,
            "reversal": false,
            "unitPrice": {
              "amount": 6360,
              "currency": "USD"
            },
            "lineTotal": {
              "amount": -636,
              "currency": "USD"
            },
            "includeFor": [
              "provider"
            ]
          }
        ],
        "protectedData": {},
        "transitions": [
          {
            "transition": "transition/request",
            "createdAt": "2018-03-27T12:30:03.100Z",
            "by": "customer"
          }
        ]
      }
    },
    {...},
    {...}
  ],
  "meta": {
    "totalItems": 3,
    "totalPages": 1,
    "page": 1,
    "perPage": 100
  }
}

// res.data
{
  data: [
    {
      id: UUID {uuid: "ef98e897-5b81-49a5-aca6-01d9759df075"},
      type: "transaction",
      attributes: {
        createdAt: new Date("2018-03-27T12:30:02.000Z"),
        processName: "preauth-with-nightly-booking",
        processVersion: 3,
        lastTransition: "transition/request",
        lastTransitionedAt: new Date("2018-03-27T12:30:03.100Z"),
        payinTotal: {
          amount: 6360,
          currency: "USD"
        },
        payoutTotal: {
          amount: 5724,
          currency: "USD"
        },
        lineItems: [
          {
            code: "line-item/day",
            quantity: 4,
            units: 2,
            seats: 2,
            reversal: false,
            unitPrice: {
              amount: 1590,
              currency: "USD"
            },
            lineTotal: {
              amount: 6360,
              currency: "USD"
            },
            includeFor: [
              "customer",
              "provider"
            ]
          },
          {
            code: "line-item/provider-commission",
            percentage: -10.0,
            reversal: false,
            unitPrice: {
              amount: 6360,
              currency: "USD"
            },
            lineTotal: {
              amount: -636,
              currency: "USD"
            },
            includeFor: [
              "provider"
            ]
          }
        ],
        protectedData: {},
        transitions: [
          {
            transition: "transition/request",
            createdAt: new Date("2018-03-27T12:30:03.100Z"),
            by: "customer"
          }
        ]
      }
    },
    {...},
    {...}
  ],
  meta: {
    totalItems: 3,
    totalPages: 1,
    page: 1,
    perPage: 100
  }
}

Query all transactions of a marketplace. Results are sorted by transaction's createdAt time in descending order (i.e. most recent transactions are returned first).

Query parameters

Parameter	Description
createdAtStart	(timestamp, optiona) Filter transactions by createdAt time. Only transactions created on or after the given time are returned. The timestamp must be in ISON 8601 format.
createdAtEnd	(timestamp, optiona) Filter transactions by createdAt time. Only transactions created before the given time are returned. The timestamp must be in ISON 8601 format.

Bookings

Example resource

{
  "data": {
    "id": "5a3e765a-06ea-4ca6-ba7f-f394ad2888a1",
    "type": "booking",
    "attributes": {
      "seats": 3,
      "start": "2018-04-20T00:00:00.000Z",
      "end": "2018-04-22T00:00:00.000Z",
      "displayStart": "2018-04-20T18:00:00.000Z",
      "displayEnd": "2018-04-22T10:00:00.000Z",
      "state": "accepted"
    }
  }
}

{
  data: {
    id: UUID {uuid: "5a3e765a-06ea-4ca6-ba7f-f394ad2888a1"},
    type: "booking",
    attributes: {
      seats: 3,
      start: new Date("2018-04-20T00:00:00.000Z"),
      end: new Date("2018-04-22T00:00:00.000Z"),
      displayStart: new Date("2018-04-20T18:00:00.000Z"),
      displayEnd: new Date("2018-04-22T10:00:00.000Z"),
      state: "accepted"
    }
  }
}

The booking resource type represents information about a booking.

Bookins are currently accessible only via the booking relationship of transaction resources.

booking resource format

Attribute	Description
seats	(number) Integer number of booked seats.
start	(string, timestamp) The date and time the booking starts. This time is used to determine what interval is matched against the listing's availability and is reserved with the booking.
end	(string, timestamp) The date and time the booking ends. The range is exclusive on the end side, i.e. the end is not reserved. This time is used to determine what interval is matched against the listing's availability and is reserved with the booking.
displayStart	(string, timestamp) The booking start display time. The display time is an arbitrary timestamp and can be different from the start time.
displayEnd	(string, timestamp) The booking end display time. The display time is an arbitrary timestamp and can be different from the end time.
state	(string) The state of the booking. See booking states.

Note that if your transaction process uses daily or nightly bookings, only the date component of the timestamp is relevant. In that case the time component of start and end timestamps is normalized to 00:00:00.000Z time but you have to interpret the timestamp in UTC time zone in order to get the correct date.

The booking displayStart and displayEnd times can optionally be set when a booking is created via a transaction. If omitted, the displayStart and displayEnd will have the same values as start and end respectively. If set, displayStart and displayEnd are stored and returned unmodified by the API (i.e. no normalization is performed for them for day- and night-based bookings, unlike the start and end times).

booking states

State	Description
pending	A new booking that has been requested by a customer.
accepted	A booking that has been accepted by the provider.
declined	A booking that has been declined by the provider or customer before it was accepted.
cancelled	A booking that has been cancelled.

booking relationships

Relationship	Resource type	Cardinality	Description
transaction	transaction	one	The transaction corresponding to a given booking. Supported nested relationships: transaction.customer and transaction.customer.profileImage.

Reviews

API prefix

/v1/integration_api/reviews

Example resource

{
  "data": {
    "id": "81a0170a-ecc2-4fe1-9aae-e86226023717",
    "type": "review",
    "attributes": {
      "type": "ofProvider",
      "state": "public",
      "rating": 5,
      "content": "The bike was awesome and everything went smoothly.\n\nThanks!",
      "createdAt": "2018-04-25T11:10:14.123Z"
    }
  }
}

{
  data: {
    id: UUID {uuid: "81a0170a-ecc2-4fe1-9aae-e86226023717"},
    type: "review",
    attributes: {
      "type": "ofProvider",
      "state": "public",
      "rating": 5,
      "content": "The bike was awesome and everything went smoothly.\n\nThanks!",
      "createdAt": new Date("2018-04-25T11:10:14.123Z")
    }
  }
}

The review resource format represent reviews posted by transaction parties about one another. Reviews are only posted during a transaction through the transaction process.

Reviews are currently accessible only via the reviews relationship of transaction resources.

review resource format

Attribute	Description
type	(string) The review type - one of ofProvider or ofCustomer. ofProvider reviews are written by customers in a transaction and are considered as reviews about both the provider and the listing in that transaction. ofCustomer reviews are written by providers and are about the customer in the transaction.
state	(string) The review state - one of public or pending.
rating	(number, integer) The rating given with the review. An integer from 1 to 5, inclusive.
content	(string) The content of the view.
createdAt	(string, timestamp) The date and time the review was written, in ISO 8601 format.

review relationships

Relationship	Resource type	Cardinality	Description
author	user	one	The user that wrote the review. Supported nested relationships: author.profileImage.
listing	listing	one	The listing that the review is about. The relationship is available only for reviews of type ofProvider.
subject	user	one	The user that the review is about. Supported nested relationships: subject.profileImage.

Messages

API prefix

/v1/integration_api/messages

Example resource

{
  "data": {
    "id": "efe37293-5e58-4f8d-8507-64616e34d22e",
    "type": "message",
    "attributes": {
      "content": "Hello,\n\nDoes the bike have winter tyres? Snow is back.",
      "createdAt": "2018-03-28T09:12:58.866Z"
    }
  }
}

{
  data: {
    id: UUID {uuid: "efe37293-5e58-4f8d-8507-64616e34d22e"},
    type: "message",
    attributes: {
      content: "Hello,\n\nDoes the bike have winter tyres? Snow is back.",
      createdAt: new Date("2018-03-28T09:12:58.866Z)"
    }
  }
}

The message resource type represents transaction messages that are sent between users as part of a conversation about transaction. Messages are always linked to a transaction.

Messages are currently accessible only via the messages relationship of transaction resources.

message resource format

Attribute	Description
content	(string) The message content.
createdAt	(string, timestamp) The date and time the message was sent in ISO 8601 format.

message relationships

Relationship	Resource type	Cardinality	Description
sender	user	one	The user that sent the message. Supported nested relationships: sender.profileImage.
transaction	transaction	one	The transaction that the message refers to.