Introduction

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

# 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"

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**

You must replace your_api_token_here with your API token.

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.

Max per_page is 100.

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**"

[
  {
    "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"
    }
}'

{
  "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

owner must be a valid ArcSite username belongs to same organization.

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
email	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
email	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

operator must be a valid ArcSite username belongs to same organization.

Get Project

curl "https://api.arcsite.com/v1/projects/<ID>" \
  -H "Authorization: Bearer **your_api_token_here**"

{
  "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.

{
  "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
email	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**"

[
  {
    "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**"

{
  "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**"

{
  "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**"

[
  {
    "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**"

{
  "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.

{
  "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.

The returned pdf_url or png_url will expire in 24 hours. They are not permanent links and should not be used in your system directly. You need to download the files from the urls for your future use.

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.