Introduction
Base url
https://api.arcsite.com/v1
Welcome to the ArcSite API 👋
The ArcSite API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Authentication
To authorize, use this code:
# With shell, you can just pass the correct header with each request
curl "https://api.arcsite.com/v1/projects" \
-H "Authorization: Bearer your_api_token"
Make sure to replace
your_api_token
with your API token.
The ArcSite API uses API tokens to authenticate requests. You can view and manage your API tokens by visiting the the ArcSite web UI..
Authentication to the API is performed via HTTP Authorization Header.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authenciation will also fail.
Authorization: Bearer **your_api_token_here**
Pagination
All list operations will be paginated in similar fashion as the GitHub API. In most cases we will paginate requests returning more than 100 results. You can control pagination with the page and per_page parameters. Pages start at 1 and the first page will be returned if no page is specified.
Attribute | Type | In | Description |
---|---|---|---|
per_page | Integer | query | The total number of objects that can be returned. Defaults to 10. |
page | Integer | query | The current page offset. Increasing this number will multiply limit. Defaults to 1. |
Projects
Query projects
curl "https://api.arcsite.com/v1/projects" \
-H "Authorization: Bearer **your_api_token_here**"
The above command returns JSON structured like this:
[
{
"id": 36029621652695040,
"name": "project 4",
"created_at": "2022-01-16T04:19:23",
"updated_at": "2022-01-16T04:19:23",
"job_number": "144111",
"customer": {
"name": "Jack",
"phone": "1441",
"second_phone": "1122",
"email": "c@arcsite.com",
"second_email": "s@arcsite.com",
"address": {
"street": "street",
"city": "city",
"county": "county",
"state": "state",
"zip_code": "300433"
}
},
"work_site_address": {
"street": "street",
"city": "city",
"county": "county",
"state": "state",
"zip_code": "300433"
},
"sale_rep": {
"name": "Wang",
"email": "h@arcsite.com",
"phone": "122122-121"
}
}
]
Returns a list of projects your organization. The projects are returned in sorted order, with the most recent created project appearing first.
HTTP Request
GET https://api.arcsite.com/v1/projects
Query Parameters
Parameter | Default | In | Description |
---|---|---|---|
page | 1 | query | Request a specific page |
per_page | 10 | query | Page size |
Create Project
curl -X POST 'https://api.arcsite.com/v1/projects' \
-H 'Authorization: Bearer **your_api_token_here**' \
-H 'Content-Type: application/json' \
-d '{
"name":"hahaa",
"job_number": "144111",
"customer": {
"name": "Jack",
"phone": "1441",
"second_phone": "1122",
"email": "c@arcsite.com",
"second_email": "s@arcsite.com",
"address": {
"street": "street",
"city": "city",
"county": "county",
"state": "state",
"zip_code": "300433"
}
},
"work_site_address": {
"street": "street",
"city": "city",
"county": "county",
"state": "state",
"zip_code": "300433"
},
"sale_rep": {
"name": "Wang",
"email": "h@arcsite.com",
"phone": "122122-121"
}
}'
The above command returns JSON structured like this:
{
"id": "36029621653386360",
"name": "nac",
"created_at": "2022-01-16T03:31:39",
"updated_at": "2022-01-16T03:31:39",
"job_number": "heeloo",
"customer": {
"name": "hello",
"phone": "122112",
"second_phone": "122112",
"email": "dev@arctuition.com",
"second_email": "dev@arctuition.com",
"address": {
"street": "address",
"city": "city",
"county": "county",
"state": "state",
"zip_code": "200544"
}
},
"work_site_address": {
"street": "street",
"city": "city",
"county": "county",
"state": "state",
"zip_code": "300433"
},
"sales_rep": {
"name": "Wang",
"email": "dev@arctuition.com",
"phone": "122112"
}
}
This endpoint creates a new project.
HTTP Request
POST https://api.arcsite.com/v1/projects
Parameters
Parameter | Type | Description |
---|---|---|
name | String | (required) Name of the project |
owner | String | (required) Owner of the project |
customer | Customer | (optional) Customer profile of the project |
job_number | String | (optional) Job number of the project |
work_site_addreess | Address | (optional) Worksite address of the project |
sales_rep | SalesRep | (optional) Sales Representative of the project |
tags | List[String] | (optional) Tags added to this project |
Project Name Rule
- Project name must be unique across the same organization.
- Project name cannot contain any of the following characters:
:
/
\
. - Project name cannot starts with
.
- Project name must be less than or equal to 200 characters.
Customer
Parameter | Type | Description |
---|---|---|
name | String | (optional) Customer name |
phone | String | (optional) Customer phone |
second_phone | String | (optional) Customer secondary phone |
String | (optional) Customer email | |
second_email | String | (optional) Customer secondary email |
address | Address | (optional) Customer address |
Address
Parameter | Type | Description |
---|---|---|
street | String | (optional) Street name |
city | String | (optional) City name |
county | String | (optional) County name |
State | String | (optional) State name |
zip_code | String | (optional) Zip Code |
SaleRep
Parameter | Type | Description |
---|---|---|
name | String | (optional) Customer name |
String | (optional) Customer email | |
phone | String | (optional) Customer phone |
Update Project
curl -X PATCH 'https://api.arcsite.com/v1/projects/<ID>' \
-H 'Authorization: Bearer **your_api_token_here**' \
-H 'Content-Type: application/json' \
-d '{
"name":"hahaa",
"job_number": "144111",
"customer": {
"name": "Jack",
"phone": "1441",
"second_phone": "1122",
"email": "c@arcsite.com",
"second_email": "s@arcsite.com",
"address": {
"street": "street",
"city": "city",
"county": "county",
"state": "state",
"zip_code": "300433"
}
},
"work_site_address": {
"street": "street",
"city": "city",
"county": "county",
"state": "state",
"zip_code": "300433"
},
"sale_rep": {
"name": "Wang",
"email": "h@arcsite.com",
"phone": "122122-121"
}
}'
This endpoint updates a project.
HTTP Request
PATCH https://api.arcsite.com/v1/projects/<id>
Parameters
Parameter | Type | Description |
---|---|---|
name | String | (required) Name of the project |
operator | String | (required) Who updates the project |
customer | Customer | (optional) Customer profile of the project |
job_number | String | (optional) Job number of the project |
work_site_addreess | Address | (optional) Worksite address of the project |
sales_rep | SalesRep | (optional) Sales Representative of the project |
Get Project
curl "https://api.arcsite.com/v1/projects/<ID>" \
-H "Authorization: Bearer **your_api_token_here**"
The above command returns JSON structured like this:
{
"id": 36029621652695040,
"name": "project 4",
"created_at": "2022-01-16T04:19:23",
"updated_at": "2022-01-16T04:19:23",
"job_number": "144111",
"customer": {
"name": "Jack",
"phone": "1441",
"second_phone": "1122",
"email": "c@arcsite.com",
"second_email": "s@arcsite.com",
"address": {
"street": "street",
"city": "city",
"county": "county",
"state": "state",
"zip_code": "300433"
}
},
"work_site_address": {
"street": "street",
"city": "city",
"county": "county",
"state": "state",
"zip_code": "300433"
},
"sale_rep": {
"name": "Wang",
"email": "h@arcsite.com",
"phone": "122122-121"
}
}
Returns project of your organization by project id,
HTTP Request
GET https://api.arcsite.com/v1/projects/<id>
Add Project Collaborators
curl -X POST 'https://api.arcsite.com/v1/projects/<ID>/add_collaborators' \
-H 'Authorization: Bearer **your_api_token_here**' \
-H 'Content-Type: application/json' \
-d '{
"collaborators": [
{"email": "dev@arctuition.com", "role": "PROJECT_ADMIN"},
{"email": "haowe12@arctui1tion.com", "role": "PROJECT_ADMIN"}
]
}
This endpoint adds collaborators to a project. Successfully added collaborators are in success_items
field of the response and failed items are in the fail_items
. This API is idempotent, so the same collaborator can be added multiple times.
The above command returns JSON structured like this:
{
"success_items": [
{
"email": "dev@arctuition.com",
"role": "PROJECT_ADMIN"
}
],
"fail_items": [
{
"data": {
"email": "haowe12@arctui1tion.com",
"role": "PROJECT_ADMIN"
},
"message": "haowe12@arctui1tion.com has not been added to your company account yet."
}
]
}
HTTP Request
POST https://api.arcsite.com/v1/projects/<id>/add_collaborators
Parameters
Parameter | Type | Description |
---|---|---|
collaborators | List[Collaborator] | (required) collaborators to add |
Collaborator
Parameter | Type | Description |
---|---|---|
string | (required) | |
role | Role | (required) Project Role |
Role
PROJECT_ADMIN
- Project Admins have full access to the project.PROJECT_COLLABORATOR
- Can create, edit and delete drawings. This role cannot delete project or manage collaborators..PROJECT_VIEWER
- Project Viewers can only view drawings.
Get Project Drawings
curl "https://api.arcsite.com/v1/projects/<ID>/drawings" \
-H "Authorization: Bearer **your_api_token_here**"
The above command returns JSON structured like this:
[
{
"id": "36029621653385418",
"name": "drawing 1"
},
{
"id": "36029621653385407",
"name": "drawing 2"
}
]
Returns drawings of a project.
HTTP Request
GET https://api.arcsite.com/v1/projects/<id>/drawings
Query Parameters
Parameter | Default | In | Description |
---|---|---|---|
page | 1 | query | Request a specific page |
per_page | 10 | query | Page size |
Drawings
Get Drawing
curl "https://api.arcsite.com/v1/drawings/<ID>" \
-H "Authorization: Bearer **your_api_token_here**"
The above command returns JSON structured like this:
{
"id": "36029621652695015",
"project_id": "28123123123",
"name": "Drawing_1_Pre-Survey_Proposal (1)-page_03_test-page_02",
"pdf_url": "https://d1umxpetlubu85.cloudfront.net/36029346774787878/36029621652694930/40c01b5a-75d5-11ec-8ea1-0242ac170007/Drawing_1_Pre-Survey_Proposal_-281-29-page_03_test-page_02.pdf?Expires=1642318765&Signature=Lh9XnGwEtt5DdZx4GAdp7J5qbJArHKS~lY39y2OjDsSRzpXPuv6H4x0RxfqYGi6gqrZxv56GMn2MiQXN9cM2VotAMpGWBsjm4cabdpLSXZNuhtqJ4k9~VBr3EyhgGIlIQk2HUlb-~McPlfbGNrbGbzj3P5mpEZ0Ce00OG0WUs3eolPEom9s4v7QNwWRrsyltFvEhZ~T4S8tRDCjyHa50al6GsNCLb5sBX7pW~oem2~GKGYj3a-kDuzCQiKLp4K7Ncc2njmDwVHThI9aSIlggbuejBa~XbWUf2WNgcbUq0~i0-e~yVN212~Qh7vHcXV4XFXQ-7k3zdxfLE8m9il5Ufg__&Key-Pair-Id=APKAIZL6W5TJO2AK7DOQ",
"png_url": "https://d1umxpetlubu85.cloudfront.net/36029346774787878/36029621652694930/40c01b5a-75d5-11ec-8ea1-0242ac170007/Drawing_1_Pre-Survey_Proposal_-281-29-page_03_test-page_02.png
}
Returns drawing of your organization by project drawing id,
HTTP Request
GET https://api.arcsite.com/v1/drawings/<id>
Get Line items
curl "https://api.arcsite.com/v1/drawings/<ID>/line_items" \
-H "Authorization: Bearer **your_api_token_here**"
The above command returns JSON structured like this:
{
"line_items": [
{
"name": "product1",
"quantity": 2.26,
"total": 0
"sku": "sku1", // sku field not exist for custom price items
},
{
"name": "product2",
"quantity": 32.57,
"total": 128.98
}
],
"subtotal": 131.24,
"discount": -31.24,
"discount_description": "discount reduce",
"markup": 100,
"markup_description": "extra fee",
"taxes": [
{
"name": "a",
"total": 20
},
{
"name": "b",
"total": 30
}
],
"total": 250
}
Get line items by drawing id.
HTTP Request
GET https://api.arcsite.com/v1/drawings/<id>/line_items
Proposals
Query Proposal Templates
curl "https://api.arcsite.com/v1/proposal_templates" \
-H "Authorization: Bearer **your_api_token_here**"
The above command returns JSON structured like this:
[
{
"id": "36029621652695041",
"name": "Proposal Template 1"
}
]
Returns a list of proposal templates of your organization.
HTTP Request
GET https://api.arcsite.com/v1/proposal_templates
Query Parameters
Parameter | Default | In | Description |
---|---|---|---|
page | 1 | query | Request a specific page |
per_page | 10 | query | Page size |
Export Proposal PDF
curl "https://api.arcsite.com/v1/export_proposal_pdf" \
-H "Authorization: Bearer **your_api_token_here**"
The above command returns JSON structured like this:
{
"url": "https://d1umxpetlubu85.cloudfront.net/36029346774973628/36029621653386370/36029621653386685/c6f62f3d-db06-42df-8138-91d80e792e5d/Drawing_1_Pre-Survey_Proposal_-281-29-page_03_test-page_02_test.pdf"
}
Export Proposal PDF by giving the proposal template id.
HTTP Request
POST https://api.arcsite.com/v1/export_proposal_pdf
Parameters
Parameter | Type | Description |
---|---|---|
template_id | String | (required) Template id from Query proposal templates |
drawing_id | String | (required) Drawing id |
Webhooks
Use incoming webhooks to get real-time updates.
ArcSite uses webhooks to notify your application when an event happens in your organization. Webhooks are particularly useful for asynchronous events like new drawing created.
A webhook enables ArcSite to push real-time notifications to your app. ArcSite uses HTTPS to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your backend systems.
You can create and manage your webhooks from the ArcSite web UI.
A of webhook payload contains both event type and payload data.
Sample webhook payload
{
"event": "project.created",
"data": {
"id": 36029621652695040,
"name": "project 4",
"created_at": "2022-01-16T04:19:23",
"updated_at": "2022-01-16T04:19:23",
"job_number": "144111",
"customer": {
"name": "Jack",
"phone": "1441",
"second_phone": "1122"
}
}
}
Built-in retries
ArcSite webhooks have built-in retry methods for 3xx, 4xx, or 5xx response status codes. If ArcSite doesn’t quickly receive a 2xx response status code for an event, webhooks will retry the event until it receives a 2xx response or up to certain times.
Project Created
project.created
Triggerd when a project is created.
Project Created Webhook Payload
Parameter | Type | Description |
---|---|---|
id | String | (required) ID of the project |
name | String | (required) Name of the project |
customer | Customer | (optional) Customer profile of the project |
job_number | String | (optional) Job number of the project |
work_site_addreess | Address | (optional) Worksite address of the project |
sales_rep | SalesRep | (optional) Sales Representative of the project |
Drawing Created
drawing.created
Triggerd when a drawing is created.
Drawing Created Webhook Payload
Parameter | Type | Description |
---|---|---|
id | String | (required) ID of the drawing |
project_id | String | (required) Project ID of the drawing |
name | String | (required) Name of the drawing |
pdf_url | String | (required) Download address of PDF format of the drawing |
png_url | String | (required) Download address of PNG format of the drawing |
Drawing Updated
drawing.updated
Triggerd when a drawing is updated.
Drawing Updated Webhook Payload
Parameter | Type | Description |
---|---|---|
id | String | (required) ID of the drawing |
project_id | String | (required) Project ID of the drawing |
name | String | (required) Name of the drawing |
file_name | String | (required) File name of the drawing |
pdf_url | String | (required) Download address of PDF format of the drawing |
png_url | String | (required) Download address of PNG format of the drawing |
Errors
ArcSite uses HTTP response codes to indicate the success or failure of a request. Codes within the 2xx range are considered as successfully completed requests. Codes within the 4xx and 5xx ranges will indicate that a failure has occurred.
We use the following error codes to manage common failures.
The ArcSite API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API token is wrong. |
404 | Not Found -- The specified resource could not be found. |
405 | Method Not Allowed -- You tried to access an API with an invalid method. |
406 | Not Acceptable -- You requested a format that isn't json. |
429 | Too Many Requests. -- You have sent too many requests in a given amount of time. |
500, 502, 503, 504 | There is an issue with ArcSite. These are rare and we will be messaged when they occur. |