openapi: 3.2.0
info:
  title: FRAYT OAUTH API
  version: '2.2'
  description: "<h2>Introduction</h2>\n<p>Welcome to the FRAYT's REST API.  Each endpoint is documented individually, and the endpoints are categorized by the resource that they primarily affect (Matches, and OAuth). By following the outlined schema of each endpoint, our API allows you to integrate FRAYT's logistics services seamlessly into your application.</p>\n\n<h3>FRAYT Terminology</h3>\n  <p>The logistics industry tends to have a wide variety of terms for a single item. So let's make sure we define our terms before getting into the API:</p>\n    <ul>\n      <li><b>Match:</b> this is an individual order placed in the FRAYT system for a driver to deliver</li>\n      <li><b>Estimate:</b> this provides a dollar amount in the response prior to it becoming a match. Estimates can be authorized into matches by passing the same payload but to the matches endpoint</li>\n    </ul>\n\n<h3>FRAYT Workflows</h3>\n  <p>Now that we have our terms defined, let's paint a bigger picture of what the life of a match looks like. These examples are the most common but are by no means exhaustive.</p>\n    <ul>\n      <li><b>Golden Path:</b> Pending (estimate)->Assigning Driver (live match to whole marketplace)->Accepted (by a driver)->En Route to Pickup->Arrived at Pickup->Picked Up<b><font color=\"red\">*</font></b>->Completed (delivered)->Charged</li>\n      <li><b>Unable to Pickup:</b> Pending->Assigning Driver->Accepted>En Route to Pickup->Arrived at Pickup->Unable to Pickup</li>\n      <li><b>Unable to Dropoff:</b> Pending->Assigning Driver->Accepted->En Route to Pickup->Arrived at Pickup->Picked Up<b><font color=\"red\">*</font></b>->En Route to Return->Arrived at Return->Charged</li>\n      <li><b>Preferred Driver:</b> Pending->Offered (only to preferred driver, not marketplace)->Accepted->En Route to Pickup->Arrived at Pickup->Picked Up<b><font color=\"red\">*</font></b>->Completed->Charged</li>\n      <p><i><b><font color=\"red\">*</font></b>Once a match is picked up, the match.stop state changes from Pending–>En Route–>Arrived–>Signed–>Delivered or Returned</i></p>\n    </ul>\n\n<h2> Endpoints and Requests</h2>\n<p>The FRAYT API endpoints are organized as <b>matches, match estimates, and oauth</b>. Once authentication has been made, the primary endpoint used will be the Matches endpoint for all estimates and matches.\n\nOur endpoints have a base url of https://api.frayt.com/api/v2.2/\n\nThe <b>schema</b> for each endpoint lists the properties <i>and provides a brief description to provide context for your mapping needs</i>. Additionally, <b>all required properties</b> are listed with a <font color=\"red\">red asterisk</font> (<font color=\"red\">*</font>).</p>\n\n\n  <h3> Authentication </h3>\n    <p>All FRAYT API requests require a valid bearer token. To generate your bearer token, you will need to hit the <a href=\"/docs/api/v2.2/#/oauth/FraytElixirWeb.API.OauthController.authenticate\" target=\"oauth\">OAuth endpoint</a> passing your Client ID and Secret in the payload.\n    To acquire your Client ID and Secret, reach out to the FRAYT team at <a href=\"mailto:dev@frayt.com\">dev@frayt.com</a>.</p>\n\n  <h3>Match Estimates </h3>\n    <p>The <a href=\"/docs/api/v2.2/#/match%20estimates/FraytElixirWeb.API.V2x2.MatchEstimateController.create\" target=\"match estimates\">match estimates endpoint</a> provides the ability to get a rate estimate, create a match, update an estimate, or turn an estimate into a match.</p>\n    <p>To receive an estimated rate for a delivery without creating the match itself, hit the POST match estimates endpoint.</p>\n    <p>To turn the estimate into a delivery (what we call a match at FRAYT), make a call to ouar PATCH match estimates endpoint.</p>\n\n  <h3>Matches </h3>\n    <p>The <a href=\"/docs/api/v2.2/#/matches/FraytElixirWeb.API.V2x2.MatchController.estimate\" target=\"matches\">matches endpoint</a> provides the ability to create a match, update a match, add a tip, or cancel a match.</p>\n    <p>To tender a delivery (what we call a match at FRAYT), pass the required payload to our POST matches endpoint.</p>\n    <p>To fetch data on a match at any point, hit the GET /matches/{id} endpoint.</p>\n\n\n<h2>Webhooks</h2>\n  <p>Webhook payloads are defined in the callbacks of each method below. You can find detailed state information under the response Schema of each callback.</p>\n  <p><i>To receive webhook updates from FRAYT, contact the FRAYT team for setup and configuration at <a href=\"mailto:dev@frayt.com\">dev@frayt.com</a></i></p>\n"
servers:
- url: https://api.frayt.com
  variables: {}
tags:
- name: oauth
paths:
  /api/v2.2/oauth/token:
    post:
      callbacks: {}
      operationId: FraytElixirWeb.API.OauthController.authenticate
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Oauth_Request'
        description: Credentials
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Oauth_Response'
          description: Success
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
          description: Invalid Credentials
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invalid_Parameters'
          description: Invalid Parameters
      summary: Get bearer token for use in protected API calls`
      tags:
      - oauth
components:
  schemas:
    Invalid_Parameters:
      description: Error response when invalid paramaters are passed
      properties:
        errors:
          items:
            properties:
              detail:
                type: string
              source:
                properties:
                  pointer:
                    type: string
                type: object
              title:
                type: string
            type: object
          type: array
      title: Invalid Parameters
      type: object
    Forbidden:
      description: Invalid/expired credentials were provided or permissions are insufficient
      example:
        code: forbidden
        message: string
      properties:
        code:
          description: Error code
          type: string
        message:
          description: Human readable message explaining the error
          type: string
      title: Forbidden
      type: object
    Oauth_Response:
      description: Issued access (bearer) token
      example:
        response:
          token: xxxxxx...
      properties:
        response:
          properties:
            token:
              description: Bearer access token
              type: string
          required:
          - token
          type: object
      required:
      - response
      title: Oauth Response
      type: object
    Oauth_Request:
      description: Company Oauth credentials
      example:
        client_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
        secret: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      properties:
        client_id:
          description: Required client ID
          type: string
        client_secret:
          description: Client secret key (optional if secret is present)
          type: string
        secret:
          description: Secret key (optional if client_secret is present)
          type: string
      required:
      - client_id
      title: Oauth Request
      type: object
  securitySchemes:
    authorization:
      scheme: bearer
      type: http