The 1099Policy API is based on REST principles with resource-oriented URLs that accept JSON request bodies and return JSON responses. Use the 1099Policy API and the keys available on your 1099Policy Dashboard to offer contractors on your platform access to on-demand, pay-as-you-go insurance.
Use the development environment secret key to step through the process of procuring insurance using 1099Policy API for test contractors and job assignments. Because the API key you use to authenticate determines whether the request runs in our production environment or in our development environment, going live on the 1099Policy platform is as easy as replacing the development secret key with the production secret key once you're ready.
To use the 1099Policy API you need to authenticate requests using API keys. Sign up for a developer account to view and manage your API keys from the the 1099Policy Dashboard. https://dashboard.1099policy.com/register
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Test mode secret keys have the prefix
t9k_test_ and live mode secret keys have the prefix
Your API tokens should be guarded closely. As a reminder, do not share your secret API keys in publicly accessible areas such as GitHub or client-side code, for example. Instead use environment variables, web server settings, startup script, or a configuration file that is excluded from your version control.
1099Policy uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the
2xx range indicate success. Codes in the
4xx range indicate an error due to the the information provided (e.g., a required parameter was omitted, a create policy request failed, etc.). Codes in the 5xx range indicate an error with 1099Policy's servers (these are rare).
4xx errors that could be handled programmatically (e.g., contractor inelgible for coverage) include an error code that briefly explains the error reported.
Our API libraries raise exceptions for many reasons, such as a failed create policy request, invalid parameters, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions.
The 1099Policy API checks every request body for an an additional
idempotency_key. We use this field to perform an idempotency check to avoid duplicate transfers in case of network failures or timeouts. For example, if a request to bind a policy fails to return a response due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one policy is created.
1099Policy's idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including
We suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.
Keys expire after 24 hours, so a new request is generated if a key is reused outside of that time frame. Results are only saved if an API endpoint started executing. You can safely retry requests that fail validation or conflicts with another request that was executing concurrently.
POST requests accept idempotency keys. Sending idempotency keys in
DELETE requests has no effect and should be avoided, as these requests are idempotent by definition.
This is the documentation for version
of the API. Last update on May 23, 2021.