# Closex ✨

[![Coverage Status](](
[![Package Version](](

🔥 Blazing-fast 🚀 Elixir library 👻️ for the API 🤖

📔 Learn more about the API: [](

📖 Documentation for this package is available on [HexDocs](

## Installation

Add `closex` to your list of dependencies in `mix.exs`:

def deps do
    {:closex, ">= 0.0.0"} # or the current stable version

## Configuration

In your config.exs:

config :closex,
  # This should be accessible from your user's account page in
  api_key: "YOUR_API_KEY",

  # This is a beta feature which will wait and retry `find_lead` and
  # `find_opportunity` requests *once* if you hit your rate limit. The intention
  # is that this will be gradually rolled out across other requests as needed.
  rate_limit_retry: true # Defaults to `false` (don't retry)

You can also read the API key from an environment variable, such as:

config :closex,
  api_key: {:system, "MY_ENV_VAR"}

## Usage

The client is essentially a wrapper around the Close.IO [REST API](

It follows the Close.IO API naming conventions as closely as possible. It supports almost everything that the REST API supports including querying leads, opportunities, users, organizations, statuses and more.

Example usage:

# Get a lead
{:ok, %{"id" => "my_lead_id", "status_id" => "my_status_id", ...}}

# Update a lead
Closex.HTTPClient.update_lead("my_lead_id", %{status_id: "new_status_id"})
{:ok, %{"id" => "my_lead_id", "status_id" => "new_status_id", ...}}

# many more ...

See [the docs]( for more examples.

You may also want to set the default client you want to use in your applicaton via your config:

# your_app/config/config.exs

config :yourapp,
  closeio_client: Closex.HTTPClient,
  ...other configuration...

Next, use it in your code:

# your_app/lib/module_which_uses_closeio.ex

defmodule YourApp.ModuleWhichUsesCloseIO do

  @closeio_client Application.fetch_env!(:your_app, :closeio_client)

  def do_things_with_a_close_io_lead(id) do
    # do things

## Mock Client

We have provided a mock client for testing purposes in your application.

Using the above configuration will allow you to override and use the `Closex.MockClient` in test mode.

# your_app/config/test.exs

config :yourapp,
  closeio_client: Closex.MockClient,
  ...other configuration...

For more details on the mock client please see [the docs](

## Options

Options will be passed through to [HTTPoison]( For example, to set a shorter timeout:

Closex.HTTPClient.get_lead("my_lead_id", timeout: 500, recv_timeout: 1_000)

### Rate limit retry

When we hit a rate limit on certain requests, there's a beta configuration to get the client to take this into account, wait a second longer than the remaining rate limit window then retry again. This can be enabled for all affected requests (see [Configuration](#configuration)) or on a per-request basis:

Closex.HTTPClient.get_lead("my_lead_id", rate_limit_retry: true)

This is only limited to certain requests as it's being trialled, if useful then we'll roll it out across other requests. The requests are:

- `find_leads`
- `find_opportunities`
- `find_all_opportunities`
- `get_users`

## Contributing

Everyone is encouraged to help improve this project. Here are a few ways you can help:

- Report bugs
- Fix bugs and submit pull requests
- Write, clarify, or fix documentation
- Suggest or add new features
- Please use the git hooks provided in the hooks directory. Use the following command to set these hooks up.

ln -s ../../hooks/ .git/hooks/pre-commit

## License


## Copyright

Copyright NextDayProperty Ltd (see LICENSE for details)