Navbar
curl
  • Offorte API
  • Authentication
  • Contacts
  • Proposals
  • Offorte API

    Welcome to the Offorte API! Here you'll find all the documentation to get your started with integrating your application with Offorte.

    Making a request

    All URLs start with https://connect.offorte.com/api/v1/{account_name}. Only HTTPS is supported and the path is prefixed with /api/v1/your_account_name.

    We use JSON for all API data, there is no root element and we use snake_case for object keys. You have to send the Content-Type header "Content-Type: application/json; charset=utf-8" when you do a POST, PATCH or PUT.

    Your account name is the subdomain name in your Offorte account address: https://companyname.offorte.com/

    Pagination

    For the list requests we paginate the results. The ratio is 50 items per page. Add the request param page to your request. For example: https://connect.offorte.com/api/v1/{account_name}/companies/?page=2

    Rate limit

    To prevent a too heavy load on our servers we've implemented a rate limit of 30 requests per 1 minute.

    Errors

    The Offorte API uses the following error codes:

    Code Meaning
    400 Bad Request -- Your request is invalid.
    401 Unauthorized -- Your API authorisation is wrong.
    403 Forbidden -- The item requested is hidden.
    404 Not Found -- The item could not be found.
    405 Method Not Allowed -- You tried to access an item with an invalid method.
    410 Gone -- The item requested has been removed from our servers.
    429 Too Many Requests -- You're requesting too many items! Slow down!
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

    Terms of use

    The Offorte General Terms and User Terms applies on the use of the API.

    Authentication

    To authenticate your application we support OAuth2. So pass allong an OAuth2 bearer token with your API request and you'll be fine.

    OAuth2

    OAuth2 is a secure option that allows third-party applications to access a server without passing user credentials or API keys. There are a lot of resources online on OAuth2

    1. Implement an OAuth2 library.

    2. Register your app within your Offorte Account (settings => API). Here you can create your app and will be assigned a client_id and client_secret. Also provide a redirect_uri where we optionally can send the verification code.

    3. Request authorization on the following url: https://{your_account_name}.offorte.com/oauth2/authorize and add the following GET params to your request:

    Param Value
    client_id {YOUR_CLIENT_ID}
    redirect_uri {YOUR_REDIRECT_URL}
    response_type 'code'

    4. Request an access token by doing a POST on the following url: https://{your_account_name}.offorte.com/oauth2/token and add the following params to your request, we will return the access code in json:

    Param Value
    client_id {YOUR_CLIENT_ID}
    client_secret {YOUR_CLIENT_SECRET}
    redirect_uri {YOUR_REDIRECT_URL}
    code {CODE} (obtained in step 3)
    grant_type 'authorization_code'

    5. Try to make an authorized request to https://connect.offorte.com/api/v1/{your_account_name}/hello Use the access code obtained in step 4 as a header Bearer authentication code

    Refresh tokens

    When your access token expires (30 days), you can generate a new access token using the refresh token you received in conjunction with your access token.

    curl -X POST https://{your_account_name}.offorte.com/oauth2/refresh-token \
    --data "grant_type=refresh_token" \
    --data "client_id=XXX" \
    --data "client_secret=XXX" \
    --data "refresh_token=XXX"
    

    Contacts

    List all companies

    GET /companies

    Returns a paginated list of companies.
    Searching on name can be done by using the optional query parameter

    Request example

    curl -X GET https://connect.offorte.com/api/v1/{account_name}/companies \
     -H 'Authorization: Bearer {ACCESS_TOKEN}' \
     -H 'Accept: application/json; charset=utf-8'
    

    Response example

    [
      {
        "id": 1234,
        "name": "Example Inc",
        "street": "Ginnekenweg 1",
        "zipcode": "4800AA",
        "city": "Breda",
        "state": "Noord-Brabant",
        "country": "the Netherlands",
        "phone": "+31 76 12344567",
        "fax": "+31 76 12344567",
        "email": "info@example.com",
        "internet": "https://www.example.com",
        "linkedin": "https://linkedin.com/example",
        "facebook": "https://facebook.com/example",
        "twitter": "https://twitter.com/example",
        "people": [
          {
            "id": 1234,
            "company_id": 1234,
            "firstname": "Chuck",
            "lastname": "Norris",
            "fullname": "Chuck Norris",
            "salutation": "Mr",
            "street": "Ginnekenweg 1",
            "zipcode": "4800AA",
            "city": "Breda",
            "state": "Noord-Brabant",
            "country": "the Netherlands",
            "phone": "+31 76 12344567",
            "mobile": "+31 76 12344567",
            "email": "info@example.com",
            "internet": "https://www.example.com",
            "linkedin": "https://linkedin.com/example",
            "facebook": "https://facebook.com/example",
            "twitter": "https://twitter.com/example"
          }
        ]
      }
    ]
    

    Get company details

    GET /companies/:id/

    Returns all company details

    Request example

    curl -X GET https://connect.offorte.com/api/v1/{account_name}/companies/:id/ \
     -H 'Authorization: Bearer {ACCESS_TOKEN}' \
     -H 'Accept: application/json; charset=utf-8'
    

    Response example

    {
      "id": 1234,
      "name": "Example Inc",
      "street": "Ginnekenweg 1",
      "zipcode": "4800AA",
      "city": "Breda",
      "state": "Noord-Brabant",
      "country": "the Netherlands",
      "phone": "+31 76 12344567",
      "fax": "+31 76 12344567",
      "email": "info@example.com",
      "internet": "https://www.example.com",
      "linkedin": "https://linkedin.com/example",
      "facebook": "https://facebook.com/example",
      "twitter": "https://twitter.com/example",
      "people": [
        {
          "id": 1234,
          "company_id": 1234,
          "firstname": "Chuck",
          "lastname": "Norris",
          "fullname": "Chuck Norris",
          "salutation": "Mr",
          "street": "Ginnekenweg 1",
          "zipcode": "4800AA",
          "city": "Breda",
          "state": "Noord-Brabant",
          "country": "the Netherlands",
          "phone": "+31 76 12344567",
          "mobile": "+31 76 12344567",
          "email": "info@example.com",
          "internet": "https://www.example.com",
          "linkedin": "https://linkedin.com/example",
          "facebook": "https://facebook.com/example",
          "twitter": "https://twitter.com/example"
        }
      ],
      "proposals": [
        {
          "id": 1234,
          "proposal_name": "Proposal you can't refuse",
          "proposal_status": "won"
        }
      ]
    }
    

    Delete company

    DELETE /companies/:id/

    Deletes a company

    Request example

    curl -X DELETE https://connect.offorte.com/api/v1/{account_name}/companies/:id/
     -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    
    

    Update company

    PATCH /companies/:id/

    Updates the company details with the provided attributes. Other (unprovided) attributes remain unchanged

    Request example

    curl -X PATCH https://connect.offorte.com/api/v1/{account_name}/companies/:id/ \
     -H 'Authorization: Bearer {ACCESS_TOKEN}' \
     -H 'Content-Type: application/json; charset=utf-8'
    

    Body

    {
      "name": "Example Inc",
      "street": "Ginnekenweg 1",
      "zipcode": "4800AA",
      "city": "Breda",
      "state": "Noord-Brabant",
      "country": "the Netherlands",
      "phone": "+31 76 12344567",
      "fax": "+31 76 12344567",
      "email": "info@example.com",
      "internet": "https://www.example.com",
      "linkedin": "https://linkedin.com/example",
      "facebook": "https://facebook.com/example",
      "twitter": "https://twitter.com/example"
    }
    

    Parameters

    name type description
    name string
    street string
    zipcode string
    city string
    state string
    country string
    phone string
    fax string
    email string
    internet string
    linkedin string
    facebook string
    twitter string

    Create company

    POST /companies/

    Creates a new company

    Request example

    curl -X POST https://connect.offorte.com/api/v1/{account_name}/companies/ \
     -H 'Authorization: Bearer {ACCESS_TOKEN}' \
     -H 'Content-Type: application/json; charset=utf-8'
    

    Body

    {
      "name": "Example Inc",
      "street": "Ginnekenweg 1",
      "zipcode": "4800AA",
      "city": "Breda",
      "state": "Noord-Brabant",
      "country": "the Netherlands",
      "phone": "+31 76 12344567",
      "fax": "+31 76 12344567",
      "email": "info@example.com",
      "internet": "https://www.example.com",
      "linkedin": "https://linkedin.com/example",
      "facebook": "https://facebook.com/example",
      "twitter": "https://twitter.com/example"
    }
    

    Parameters

    name type description
    name string
    street string
    zipcode string
    city string
    state string
    country string
    phone string
    fax string
    email string
    internet string
    linkedin string
    facebook string
    twitter string

    List people

    GET /companies/:id/people/

    Returns a paginated list of the people in a company.

    Request example

    curl -X GET https://connect.offorte.com/api/v1/{account_name}/companies/:id/people/ \
     -H 'Authorization: Bearer {ACCESS_TOKEN}' \
     -H 'Accept: application/json; charset=utf-8'
    

    Response example

    [
      {
        "id": 1234,
        "company_id": 1234,
        "email": "info@example.com",
        "firstname": "Chuck",
        "lastname": "Norris",
        "fullname": "Chuck Norris",
        "salutation": "Mr",
        "street": "Ginnekenweg 1",
        "zipcode": "4800AA",
        "city": "Breda",
        "state": "Noord-Brabant",
        "country": "the Netherlands",
        "phone": "+31 76 12344567",
        "mobile": "+31 76 12344567",
        "internet": "https://www.example.com",
        "linkedin": "https://linkedin.com/example",
        "facebook": "https://facebook.com/example",
        "twitter": "https://twitter.com/example"
      }
    ]
    

    Create people

    POST /companies/:id/people/

    Creates a new person in a company. Fullname and e-mail are required

    Request example

    curl -X POST https://connect.offorte.com/api/v1/{account_name}/companies/:id/people/ \
     -H 'Authorization: Bearer {ACCESS_TOKEN}' \
     -H 'Content-Type: application/json; charset=utf-8'
    

    Body

    {
      "email": "info@example.com",
      "firstname": "Chuck",
      "lastname": "Norris",
      "fullname": "Chuck Norris",
      "salutation": "Mr",
      "street": "Ginnekenweg 1",
      "zipcode": "4800AA",
      "city": "Breda",
      "state": "Noord-Brabant",
      "country": "the Netherlands",
      "phone": "+31 76 12344567",
      "mobile": "+31 76 12344567",
      "internet": "https://www.example.com",
      "linkedin": "https://linkedin.com/example",
      "facebook": "https://facebook.com/example",
      "twitter": "https://twitter.com/example"
    }
    

    Parameters

    name type description
    email string
    firstname string
    lastname string
    fullname string
    salutation string
    street string
    zipcode string
    city string
    state string
    country string
    phone string
    mobile string
    internet string
    linkedin string
    facebook string
    twitter string

    Get people details

    GET /companies/:id/people/:people_id/

    Returns all details of a person

    Request example

    curl -X GET https://connect.offorte.com/api/v1/{account_name}/companies/:id/people/:people_id/ \
     -H 'Authorization: Bearer {ACCESS_TOKEN}' \
     -H 'Accept: application/json; charset=utf-8'
    

    Response example

    {
      "id": 1234,
      "company_id": 1234,
      "email": "info@example.com",
      "firstname": "Chuck",
      "lastname": "Norris",
      "fullname": "Chuck Norris",
      "salutation": "Mr",
      "street": "Ginnekenweg 1",
      "zipcode": "4800AA",
      "city": "Breda",
      "state": "Noord-Brabant",
      "country": "the Netherlands",
      "phone": "+31 76 12344567",
      "mobile": "+31 76 12344567",
      "internet": "https://www.example.com",
      "linkedin": "https://linkedin.com/example",
      "facebook": "https://facebook.com/example",
      "twitter": "https://twitter.com/example"
    }
    

    Delete people

    DELETE /companies/:id/people/:people_id/

    Deletes a person

    Request example

    curl -X DELETE https://connect.offorte.com/api/v1/{account_name}/companies/:id/people/:people_id/
     -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    
    

    Update people

    PATCH /companies/:id/people/:people_id/

    Updates the person details with the provided attributes. Other (unprovided) attributes remain unchanged

    Request example

    curl -X PATCH https://connect.offorte.com/api/v1/{account_name}/companies/:id/people/:people_id/ \
     -H 'Authorization: Bearer {ACCESS_TOKEN}' \
     -H 'Content-Type: application/json; charset=utf-8'
    

    Body

    {
      "email": "info@example.com",
      "firstname": "Chuck",
      "lastname": "Norris",
      "fullname": "Chuck Norris",
      "salutation": "Mr",
      "street": "Ginnekenweg 1",
      "zipcode": "4800AA",
      "city": "Breda",
      "state": "Noord-Brabant",
      "country": "the Netherlands",
      "phone": "+31 76 12344567",
      "mobile": "+31 76 12344567",
      "internet": "https://www.example.com",
      "linkedin": "https://linkedin.com/example",
      "facebook": "https://facebook.com/example",
      "twitter": "https://twitter.com/example"
    }
    

    Parameters

    name type description
    email string
    firstname string
    lastname string
    fullname string
    salutation string
    street string
    zipcode string
    city string
    state string
    country string
    phone string
    mobile string
    internet string
    linkedin string
    facebook string
    twitter string

    Proposals

    List all proposals

    GET /proposals/:status

    Returns a paginated list of proposals by status (edit|open|won|lost|closed).
    Searching can be done by using the optional query parameter, the provided status will then be ignored

    Request example

    curl -X GET https://connect.offorte.com/api/v1/{account_name}/proposals/:status \
     -H 'Authorization: Bearer {ACCESS_TOKEN}' \
     -H 'Accept: application/json; charset=utf-8'
    

    Response example

    [
      {
        "id": 1234,
        "company_id": 1234,
        "company_name": "Example Inc",
        "name": "Proposal you can't refuse",
        "status": "won",
        "price_total": 15000,
        "version_id": 1234
      }
    ]
    

    Get proposal details

    GET /proposals/:id/details/

    Returns all proposal details

    Request example

    curl -X GET https://connect.offorte.com/api/v1/{account_name}/proposals/:id/details/ \
     -H 'Authorization: Bearer {ACCESS_TOKEN}' \
     -H 'Accept: application/json; charset=utf-8'
    

    Response example

    {
      "id": 1234,
      "name": "Proposal you can't refuse",
      "status": "won",
      "type": "magazine",
      "remarks": "Make some modifications as requested by Vegan Seagal",
      "price_total": 15000,
      "date_modified": "15 jun 2018 (06:49)",
      "company": {
        "name": "Example Inc",
        "street": "Ginnekenweg 1",
        "zipcode": "4800AA",
        "city": "Breda",
        "state": "Noord-Brabant",
        "country": "the Netherlands",
        "phone": "+31 76 12344567",
        "fax": "+31 76 12344567",
        "email": "info@example.com",
        "internet": "https://www.example.com",
        "linkedin": "https://linkedin.com/example",
        "facebook": "https://facebook.com/example",
        "twitter": "https://twitter.com/example"
      },
      "comments": [
        {
          "id": 1234,
          "date": "15 jun 2018 (06:49)",
          "comment": "Are there no surprises in the costs?",
          "type": "client",
          "firstname": "Chuck",
          "lastname": "Norris",
          "email": "info@example.com",
          "company_name": "Example Inc"
        }
      ],
      "logs": {
        "summary": {
          "views": 2,
          "pdf": 0,
          "recent_view": "15 jun 2018 (06:49)",
          "last_modified_date": "15 jun 2018 (06:49)",
          "last_modified_user": "15 jun 2018 (06:49)"
        },
        "history": [
          {
            "date": "15 jun 2018 (06:49)",
            "person": "Vegan Seagal",
            "action": "proposal: viewed pdf",
            "type": "client"
          }
        ]
      },
      "pages_total": 9,
      "emails": [
        {
          "id": 1234,
          "date_sended": "15 jun 2018 (06:49)",
          "proposal_version_nr": 1234,
          "message": "Dear {company_people_firstname}, hereby you receive our proposal for ...",
          "sended_by": "Johnny Vegas",
          "receivers": [
            {
              "fullname": "Chuck Norris",
              "email": "info@example.com"
            }
          ]
        }
      ]
    }