openapi: 3.0.3
info:
  title: API
  version: '1.0'
  contact:
    name: FreeCRM
    email: info@cogmento.com
  description: |
    # FreeCRM API

    ## This is a live document
    We're currently documenting our API here, and this is a live document that will keep on changing
    and evolving as we progress. 

    ## Standard response format

    All resposes that return a listing will contain the array of objects within a `results` key,
    while all requests that return a single object will contain it within a `result` key.\
    sssThere are a few exceptions to this, most notably is the `/templates/` calls which return an
    object where each key is a model type and the value is an array of fields.
    Responses also contain a `success` flag which should be `true` and a `process_time` property
    showing how long it took the API to complete compiling the response.

    ## Authentication

    Authentication is perfomed by sending an `Authorization` header with a value of
    `Token {ACCESS_TOKEN}` with each request.\
    The access token is retrieved by performing a call to the `/auth/` endpoint providing
    the user's email and password.\
    *Note* that a Successful authentication also returns a `urls` object which describes which
    environment this account belongs to. For example, if your account is part of the `eu`
    environment, the API urls for the EU API will be returned and those should be used
    for subsequent requests.\
    Authentication is normally done against the master environment (.com).

    ## Data models

    Most data models in FreeCRM are made of a few basic fixed fields and any number of
    dynamic fields defined by the `template` your account is using.\
    Dynamic fields can be managed, new fields added, existing fields modified etc.
    The models described in the API include the fixed fields of each data model, however,
    your return objects will contain any additional fields defined for your records.\
    For example, a `Deal` record will contain a `title` and `description` but using the
    default unmodified template, it will also contain fields for `next_steps` and `status`\
    You can use the `/templates/` endpoint to retrieve your account's templates in advance.
    The templates describe in full the complete structrue of each data model, including labels,
    restrictions, options, etc.\
    When fetching records, sometimes the result will contain a subset of the record's fields.
    For example, when fetching a list of contacts, the contact records are not expanded to
    load each contact's cases or phone calls. However, when loading a single record, all
    related records are fetched as well. So when a single full contact record is fetched,
    it will contain references to all cases, calls, events, documents etc.\

    *Note* that the templates allow you to label fields in your own language.

    ## Filtering

    Most listing GET requests allow a `filter`, along side `start` and `limit` parameters.\
    `start` and `limit` define the range of records to return in a query set.\
    `filter` is a URL encode JSON object describing how to filter the data returned.

    ## Using the API playground

    In order to use the API calls using the Swagger UI, you will need to perform an
    `auth` first, retrieve your token and use it to Authorize all future calls to the API.
    Click the *Authorize* button to input your token after you fetch it via the `/auth/` call.
    *Remember* that the value is `Token {ACCESS_TOKEN}` and not just the token by itself.

servers:
  - url: http://localhost:8002/api/1
    description: Local development server
  - url: https://api.cogmento.com/api/1
    description: Main production server

paths:
  /auth/:
    $ref: './paths/auth.yaml#/Authenticate'

  /auth/user/:
    $ref: './paths/auth.yaml#/AuthUserInfo'

  /account/user/password/reset/:
    $ref: './paths/auth.yaml#/PasswordReset'

  /templates/{model_type}/:
    $ref: './paths/templates.yaml'

  /account/:
    $ref: './paths/account.yaml#/Account'

  /account/settings/:
    $ref: './paths/account.yaml#/AccountSettings'

  /account/users/settings/:
    $ref: './paths/user.yaml#/UserSettings'

  /billing/calls/balance/:
    $ref: './paths/billing.yaml#/CallBalance'

  # /billing/plan/subscribe:
  #   $ref: './paths/billing.yaml#/BillingPlanSubscribe'

  /search/:
    $ref: './paths/search.yaml#/Search'

  /contacts/:
    $ref: './paths/contacts.yaml#/Contacts'

  /contacts/{contact_id}/:
    $ref: './paths/contacts.yaml#/Contact'

  /companies/:
    $ref: './paths/companies.yaml#/Companies'

  /companies/{company_id}/:
    $ref: './paths/companies.yaml#/Company'

  /cases/:
    $ref: './paths/cases.yaml#/Cases'

  /cases/{case_id}/:
     $ref: './paths/cases.yaml#/Case'

  /tasks/:
    $ref: './paths/tasks.yaml#/Tasks'

  /tasks/{task_id}/:
    $ref: './paths/tasks.yaml#/Task'

  /deals/:
    $ref: './paths/deals.yaml#/Deals'
    
  /deals/{deal_id}/:
    $ref: './paths/deals.yaml#/Deal'

  /products/:
    $ref: './paths/products.yaml#/Products'
    
  /products/{product_id}/:
    $ref: './paths/products.yaml#/Product'

  /products/{product_id}/images/:
    $ref: './paths/products.yaml#/ProductImages'
  
  /products/{product_id}/images/{product_image_id}/:
    $ref: './paths/products.yaml#/ProductImageDelete'

  /documents/:
    $ref: './paths/documents.yaml#/Documents'

  /documents/download/{document_id}/:
    $ref: './paths/documents.yaml#/DocumentDownload'

  /documents/{document_id}/assign/{model_type}/{model_id}/:
    $ref: './paths/documents.yaml#/DocumentAssign'

  /reports/geo/{model_type}/:
    $ref: './paths/search.yaml#/AddressSearch'

  /forms/:
    $ref: './paths/forms.yaml#/Forms'

  /form/{form_id}/:
    $ref: './paths/forms.yaml#/Form'
  
  /attach/{source}/{source_id}/to/{target}/{target_id}/:
    $ref: './paths/entities.yaml#/Attach'

  /resolve/{did}/:
    $ref: './paths/vcm.yaml#/ResolveDID'
 
components:
  parameters:
    filter:
      $ref: './components/parameters.yaml#/filter'
    limit:
      $ref: './components/parameters.yaml#/limit'
    start:
      $ref: './components/parameters.yaml#/start'
    sort:
      $ref: './components/parameters.yaml#/sort'
    export:
      $ref: './components/parameters.yaml#/export'

  securitySchemes:
    ApiKeyAuth:
      $ref: './components/security.yaml#/ApiKeyAuth'

  schemas:
    ProcessTime:
      $ref: './components/schemas.yaml#/ProcessTime'
    Id: 
      $ref: './components/schemas.yaml#/Id'
    RecordTypes:
      $ref: './components/schemas.yaml#/RecordTypes'
    RecordTypesExtra:
      $ref: './components/schemas.yaml#/RecordTypesExtra'
    CoreFields:
      $ref: './components/schemas.yaml#/CoreFields'
    EditableCoreFields:
      $ref: './components/schemas.yaml#/EditableCoreFields'
    View:
      $ref: './components/schemas.yaml#/View'
    Field:
      $ref: './components/schemas.yaml#/Field'
    Fields:
      $ref: './components/schemas.yaml#/Fields'
    ModelTemplate:
      $ref: './components/schemas.yaml#/ModelTemplate'
    IdName:
      $ref: './components/schemas.yaml#/IdName'
    Filter:
      $ref: './components/schemas.yaml#/Filter'
    FilterOperator:
      $ref: './components/schemas.yaml#/FilterOperator'
    ListingResponse:
      $ref: './components/schemas.yaml#/ListingResponse'
    Response:
      $ref: './components/schemas.yaml#/Response'
    SystemPaths:
      $ref: './components/schemas.yaml#/SystemPaths'
    BillingPlan: 
      $ref: './components/schemas.yaml#/BillingPlan'
    UserBasic:
      $ref: './components/schemas.yaml#/UserBasic'
    Account:
      $ref: './components/schemas.yaml#/Account'
    User:
      $ref: './components/schemas.yaml#/User'
    UserSettings:
      $ref: './components/schemas.yaml#/UserSettings'
    AccountSettings:
      $ref: './components/schemas.yaml#/AccountSettings'
    CommunicationChannel:
      $ref: './components/schemas.yaml#/CommunicationChannel'
    ContactBasic:
      $ref: './components/schemas.yaml#/ContactBasic'
    ContactBasicChannels:
      $ref: './components/schemas.yaml#/ContactBasicChannels'
    ContactBase:
      $ref: './components/schemas.yaml#/ContactBase'
    Contact:
      $ref: './components/schemas.yaml#/Contact'
    ContactArray:
      $ref: './components/schemas.yaml#/ContactArray'
    CompanyContact:
      $ref: './components/schemas.yaml#/CompanyContact'
    CompanyBase:
      $ref: './components/schemas.yaml#/CompanyBase'
    Company: 
      $ref: './components/schemas.yaml#/Company'
    CompanyArray:
      $ref: './components/schemas.yaml#/CompanyArray'
    CaseBase:
      $ref: './components/schemas.yaml#/CaseBase'
    Case: 
      $ref: './components/schemas.yaml#/Case'
    CaseArray:
      $ref: './components/schemas.yaml#/CaseArray'
    TaskBase:
      $ref: './components/schemas.yaml#/TaskBase'
    Task:
      $ref: './components/schemas.yaml#/Task'
    TaskArray:
      $ref: './components/schemas.yaml#/TaskArray'
    Product:
      $ref: './components/schemas.yaml#/Product'
    ProductImage:
      $ref: './components/schemas.yaml#/ProductImage'
    DealBase:
      $ref: './components/schemas.yaml#/DealBase'
    Deal:
      $ref: './components/schemas.yaml#/Deal'
    DealArray:
      $ref: './components/schemas.yaml#/DealArray'
    DealContactStage:
      $ref: './components/schemas.yaml#/DealContactStage'
    DealContact:
      $ref: './components/schemas.yaml#/DealContact'
    DealProduct:
      $ref: './components/schemas.yaml#/DealProduct'
    Address:
      $ref: './components/schemas.yaml#/Address'
    Form:
      $ref: './components/schemas.yaml#/Form'
    FormElement:
      $ref: './components/schemas.yaml#/FormElement'