NAV

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"
    },
    "sales_rep": {
      "name": "Wang",
      "email": "h@arcsite.com",
      "phone": "122122-121"
    },
    "tags": ["tag1", "tag2"]
  }
]

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"
    },
    "sales_rep": {
        "name": "Wang",
        "email": "h@arcsite.com",
        "phone": "122122-121"
    },
    "tags": ["tag1", "tag2"]
}'

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"
  },
  "tags": ["tag1", "tag2"]
}

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 Integrations

ArcSite supports integration with various external platforms. Once Project creation is complete, you can use the standard integration solutions we provide for different platforms to integrate your Project. After integration is completed, your Project will gain additional functionalities to support data synchronization and interactions with third-party platforms. For specific details, you can visit the integration module of OpenAPI.

Project Name Rule

  1. Project name must be unique across the same organization.
  2. Project name cannot contain any of the following characters: : / \.
  3. Project name cannot starts with .
  4. 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"
    },
    "sales_rep": {
        "name": "Wang",
        "email": "h@arcsite.com",
        "phone": "122122-121"
    },
    "tags": ["tag1", "tag2"]
}'

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
tags List[String] (optional) Tags for this 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"
  },
  "sales_rep": {
    "name": "Wang",
    "email": "h@arcsite.com",
    "phone": "122122-121"
  },
  "tags": ["tag1", "tag2"]
}

Returns project of your organization by project id,

HTTP Request

GET https://api.arcsite.com/v1/projects/<id>

Search Projects

curl -X PATCH 'https://api.arcsite.com/v1/projects/search' \
-H 'Authorization: Bearer **your_api_token_here**' \
-H 'Content-Type: application/json' \
-d '{
    "project_name":"Updated project name",
    "tags": ["Tag 1"]
}'

The above command returns JSON structured like this:

[
  {
    "id": 36029621652695040,
    "name": "Updated project name",
    "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"
    },
    "sales_rep": {
      "name": "Wang",
      "email": "h@arcsite.com",
      "phone": "122122-121"
    },
    "tags": [
      "Tag 1"
    ]
  }
]

Searching projects by conditions and returns the list of filtered projects in your organization. The projects are returned in sorted order, with the most recent created project appearing first.

HTTP Request

POST https://api.arcsite.com/v1/projects/search

Parameters

Parameter Type Description
project_name String (optional) To filter projects which contains the value
tags List[String] (optional) To filter projects by the tags list.

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
email string (required)
role Role (required) Project Role

Role

  1. PROJECT_ADMIN - Project Admins have full access to the project.
  2. PROJECT_COLLABORATOR - Can create, edit and delete drawings. This role cannot delete project or manage collaborators..
  3. 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

Returns drawings of a project.

Import PDF

Your uploaded PDF will be split to multiple pages, one ArcSite drawing will be created for each page.

# upload a local file.
curl --location 'https://api.arcsite.com/v1/projects/<project_id>/import_pdf' \
-H "Authorization: Bearer **your_api_token_here**"
--form 'file=@"/<file_path>/<file_name.pdf>"'

# or pass the file url directly.

curl --location 'https://api.arcsite.com/v1/projects/<project_id>/import_pdf' \
-H "Authorization: Bearer **your_api_token_here**"
--form 'file_url="https://file_url.pdf"'

The above command returns JSON structured like this:

{
  "drawings": [
    {
      "id": "36029621653385418"
    },
    {
      "id": "36029621653385407"
    }
  ]
}

HTTP Request

POST https://api.arcsite.com/v1/projects/<project_id>/import_pdf

Request Payload

Parameter In Description
file Body The binary pdf file to be uploaded
file_url Body The URL of a public accessable pdf file link

Returns list of drawings created.

Archive Project

This endpoint archives a project by project id. The archived project will be hidden from the project list. You can use Unarchive Project to unarchive the project.

curl -X POST 'https://api.arcsite.com/v1/projects/<ID>/archive' \
-H 'Authorization: Bearer **your_api_token_here**' \
-H 'Content-Type: application/json'

The above command returns JSON structured like this:

{}

HTTP Request

POST https://api.arcsite.com/v1/projects/<ID>/archive

Unarchive Project

This endpoint unarchive a project by project id.

curl -X POST 'https://api.arcsite.com/v1/projects/<ID>/unarchive' \
-H 'Authorization: Bearer **your_api_token_here**' \
-H 'Content-Type: application/json'

The above command returns JSON structured like this:

{}

HTTP Request

POST https://api.arcsite.com/v1/projects/<ID>/unarchive

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",
  "dxf_url": "https://cdn-files-1-test.arcsite.com/36029346774973628/36029621653508440/_attach_282299611393362/Web_hook_location_photo.dxf?Expires=1711623376&Signature=qZSQPST2tdtKM9URUDEIdnwJiXSpNxRabMtmjg6hzdizcVmKJ4UIF-F~0LLiF1LT2y~vbx73CHDNFhZZgBNSjzWszV123qWOn68NyfU6fMdWRlMu4P51q7SWRmxMTlcnMGrF8F29HeilhnZOhBTiF~9oHPa62KRM7Duuq6z-T1RAF7w8mcZH46N4A3wXUyvcIeTaX4jbxCLQ83l2AGsFonD-NVwjeeuNba3MnrwpsTdBIUEbZXnRHNWYJx0i0HhENpr4xJLnX0lDAh9fXI2Zfo8MIapbm7iz8IhTUkwjRdjWU35uabdob1YJ19qVEMoHMqjnftEEkw7n44CYBYUY9w__&Key-Pair-Id=APKAIZL6W5TJO2AK7DOQ"
}

Returns drawing of your organization by project drawing id,

HTTP Request

GET https://api.arcsite.com/v1/drawings/<id>

Query Parameters

Parameter Default In Description
drawing_version_id Optional[String] query The ID of the drawing version

Response Schema

Name Type Description
id String The ID of the drawing
project_id String The ID of the project
name String The name of the drawing
pdf_url String | null The URL of the PDF file
png_url String | null The URL of the PNG file
dxf_url String | null The URL of the DXF file

Product Items

You can get product items from a drawing with the following APIs.

Export Proposal

Export Proposal Sample

Export Takeoff

Export Takeoff Sample

Get Proposal 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
      "product_id": "19923123", // not exist for custom price items
      "sku": "sku1", //  not exist for custom price items
      "price": 3.5, //   not exist for custom price items
      "unit": "FT", //   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

Query Parameters

Parameter Default In Description
drawing_version_id Optional[String] query The ID of the drawing version

Response Schema

Name Type Description
line_items List[LineItem] All product line items
subtotal Number The subtotal of all items before discounts and markups
discount Number The total amount of discount applied
discount_description String Description or reason for the discount
markup Number The total amount of markup added
markup_description String Description or reason for the markup
taxes List[TaxItem] All taxes applied
drawing_version_id String The version id of the drawing

LineItem

Name Type Description
name String The name of the product
quantity Number The quantity of the product
total Number Item total after discounts and markup applied
price Number? Item total before discounts and markup applied; not provided for custom price items
sku String? The stock keeping unit of the product; not provided for custom price items
unit String? The unit of measurement for the product's quantity; not provided for custom price items
product_id String? The ID of the product; not provided for custom price items
price_part_items List[PricePartItem]? Detail of price part items; not provided for custom price items

PricePartItem

Name Type Description
name String The name of price part option
sku String The sku of price part option
price Number The total price of price part option
cost Number The total cost of price part option
quantity Number The total quantity of price part option
unit String The final unit of price part option

TaxItem

Name Type Description
name String The name of the tax
total Number The total amount of tax

Get Takeoff Line items

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

The above command returns JSON structured like this:

{
  "takeoff_items": [
    {
      "name": "with attributes",
      "quantity": 300,
      "unit": "Amount",
      "sku": "GM-100",
      "product_id": "287386775856064026",
      "items": [
        {
          "quantity": 1,
          "unit": "Each",
          "sequence_number": "1",
          "attributes": [
            {
              "name": "cc",
              "value": null,
              "type": "TEXT"
            },
            {
              "name": "d",
              "value": "Some text",
              "type": "TEXT"
            },
            {
              "name": "yesno",
              "value": true,
              "type": "CHECKBOX"
            },
            {
              "name": "photo",
              "value": [
                "https://cdn-files-1-test.arcsite.com/36029346774973628/282299611419718/282299611419728/F4AF22A9-F011-4214-8729-CAF3F1F9D9F6.jpg?Expires=1711452610&Signature=sQz~sNF6xPGRPTvPBKyyXgKlA6jh0VSM6mXVpJ63XgYdCE1gat-nT~ZDXtcm~jEoK46UnUWU1ZlXPAiDx5IPwV25X1-pSb~jbXwdlkcz2jPkZPUN-ZWdaCvbMgTLJRvQw-V2RiUyrF83O5GLhJMVut8lfqsGjN3dgh5AtUc53h05dGRYbW-h-d6ItuSbebOTeZSXr8PCSl~n59wgfMRa5DdEilILGNZvGpM2kMaesHYBTiXfv1Z40Fv9rmRa~TLR~tefuEPDpkJWud4aAw7t1GTCSyaeXKL23fELMu~CTWMKvQ-TOqfBsbtBiEzUkrl67qgzDUD1HGimpZ3qweyf-w__&Key-Pair-Id=APKAIZL6W5TJO2AK7DOQ"
              ],
              "type": "PHOTO"
            },
            {
              "name": "start_date",
              "value": "2024-03-25T09:36:42.031Z",
              "type": "DATE"
            }
          ]
        }
      ]
    }
  ]
}

Get takeoff items by drawing id.

HTTP Request

GET https://api.arcsite.com/v1/drawings/<id>/takeoff_items

Query Parameters

Parameter Default In Description
drawing_version_id Optional[String] query The ID of the drawing version

Response Schema

Name Type Description
takeoff_items List[TakeffItemByProduct] Takeoff items group by product

TakeffItemByProduct

Name Type Description
name String The name of the product
quantity Number The total quantity of the product
unit String The unit of measurement for the product's quantity
sku String The stock keeping unit of the product
product_id String The ID of the product
items List[TakeoffItem] The takeoff items of the product

TakeoffItem

Name Type Description
quantity Number For geometric products, we use the quantity shown in the drawing. But for shape or virtual products, the quantity is always just one.
sequence_number String Sequence Number for Shape product
unit String The input unit defined by the product
attributes List[TakeoffAttribute] The attributes of of the item

TakeoffAttribute

Name Type Description
type String The type of the attribute. Can be one of "TEXT", "PHOTO", "CHECKBOX", or "DATE".
value String, List[String], Boolean (optional) The value of the attribute. The type of this field depends on the type field:
- If type is "TEXT", value is a string.
- If type is "PHOTO", value is a list of photo URLs.
- If type is "CHECKBOX", value is a boolean.
- If type is "DATE", value is a string in ISO format.

Products

Query products

curl "https://api.arcsite.com/v1/products" \
  -H "Authorization: Bearer **your_api_token_here**"

The above command returns JSON structured like this:

[
  {
    "id": "1",
    "name": "product 1",
    "sku": "abc",
    "description": "product 1 description",
    "cost": 20.0
  }
]

Returns a list of products your organization. The products are returned in sorted order, with the most recent created product appearing first.

HTTP Request

GET https://api.arcsite.com/v1/products

Query Parameters

Parameter Default In Description
page 1 query Request a specific page
per_page 10 query Page size

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.

Secure your endpoint

We highly recommend you secure your integration by ensuring your handler verifies that all webhook request are generated by ArcSite.

The following section describes how to verify webhook signatures:

Retrieving your endpoint’s secret

Use the ArcSite Webhooks web UI to get the webhook secret. ArcSite generates a unique secret key for each webhook.

Webhhoks

Sample webhook header

{
  "ArcSite-Signature": "t=1716975491,v=5f43f28c3d33c34b18634399a8e3bb69dcfb9f146cea562289306d783187d0f1"
}

Verifying the signature

To verify the signature, you need to compare the signature in the header of the incoming webhook request with the signature using the secret and the request body. The ArcSite-Signature header included in each signed event contains a timestamp and signature that you must verify. The timestamp is prefixed by t=, and the signature is prefixed by a v=.

Python Example

import hmac
import hashlib
from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt


SECRET = 'your_webhook_secret'


def verify_webhook(header, payload, secret):
    # Extract timestamp and signature
    elements = dict(item.split('=') for item in header.split(','))
    timestamp, signature = elements['t'], elements['v']
    # Prepare signed payload string
    signed_payload = f"{timestamp}.{payload}"
    # Compute expected signature
    expected_signature = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
    # Verify signature
    return hmac.compare_digest(signature, expected_signature)


# Django Example
@csrf_exempt
def webhook_handler(request):
    if request.method == 'POST':
        header = request.headers.get('ArcSite-Signature')
        payload = request.body.decode('utf-8')
        if not verify_webhook(header, payload, SECRET):
            return HttpResponse('Invalid signature or timestamp.', status=400)
        # TODO Process the valid webhook payload here
        return HttpResponse('Webhook received successfully.', status=200)
    return HttpResponse('Method not allowed.', status=405)

Step 1: Extract the timestamp and signature from the header

Split the header using the , character as the separator to get a list of elements. Then split each element using the = character as the separator to get a prefix and value pair. The value for the prefix t corresponds to the timestamp and the prefix v to the signature. You can discard all other elements.

Step 2: Prepare the signed_payload string

The signed_payload string is created by concatenating:

Step 3: Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use the webhook’s secret as the key, and use the signed_payload string as the message.

Step 4: Compare the signature

Compare the signature in the header to the expected signature.

NodeJS Example

const express = require("express");
const crypto = require("crypto");

const app = express();
const SECRET = "your_webhook_secret";

app.use(express.raw({ type: "*/*" }));

function verifyWebhook(header, payload, secret) {
  // Extract timestamp and signature
  const elements = header.split(",").reduce((acc, element) => {
    const [key, value] = element.split("=");
    acc[key] = value;
    return acc;
  }, {});
  const signature = elements["v"];
  // Prepare signed payload string
  const signedPayload = `${elements["t"]}.${payload}`;
  // Compute expected signature
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");
  // Verify signature
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

app.post("/webhook", (req, res) => {
  const header = req.headers["arcsite-signature"];
  const payload = req.body.toString("utf-8");
  if (!verifyWebhook(header, payload, SECRET)) {
    return res.status(400).send("Invalid signature.");
  }
  // TODO Process the valid webhook payload here
  res.status(200).send("Webhook received successfully.");
});

app.listen(3000, () => {
  console.log(`Server is running on port 3000`);
});

Project Created

project.created Triggered when a project is created.

Project Created Webhook Payload

Parameter Type Description
id String ID of the project
name String 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

The drawing.created webhook will be triggered when a drawing is created by uploading PDF files on the user site or manually uploading some newly created drawing to the cloud from the ArcSite App.

Drawing Created Webhook Payload

Parameter Type Description
id String ID of the drawing
project_id String Project ID of the drawing
name String Name of the drawing
pdf_url String Download address of PDF format of the drawing
png_url String Download address of PNG format of the drawing

Drawing Updated

The drawing.updated webhook is triggered whenever a drawing is manually re-uploaded to the cloud from the ArcSite App after its initial creation.

Drawing Updated Webhook Payload

Parameter Type Description
id String ID of the drawing
project_id String Project ID of the drawing
name String Name of the drawing
pdf_url String Download address of PDF format of the drawing
png_url String Download address of PNG format of the drawing

Proposal PDF Signed

proposal.signed Triggered when a proposal is signed in the app.

Proposal PDF signed Webhook Payload

Parameter Type Description
project_id String Project ID of the drawing
name String File name of the signed document
url String Download address of the signed pdf
drawing_id String The associated drawing id of the signed pdf
drawing_version_id String The associated drawing version id of the signed pdf

Proposal Sent

proposal.sent Triggered when a proposal is sent to customer.

Proposal Sent Webhook Payload

Parameter Type Description
project_id id Approved proposal related project ID
proposal_id id Proposal ID
name String Proposal name
customer_name String Proposal customer name
contact_email String The sales email
sales_representative String The sales name
proposal_options List[ProposalOption] The proposal option data list

ProposalOption

Parameter Type Description
name String Proposal option name
drawing_id String The proposal option associated drawing ID
drawing_version_id String The proposal option associated drawing version ID
total Number The total of the proposal option
pdf_url String Download address of the proposal option pdf file

Proposal Approved

proposal.approved Triggered when a proposal is approved by customer.

Proposal Approved Webhook Payload

Parameter Type Description
project_id id Approved proposal related project ID
proposal_id id Proposal ID
name String Proposal name
customer_name String Proposal customer name
contact_email String The sales email
sales_representative String The sales name
approved_option ProposalOption Approved proposal option data

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.

Integrations

Improveit360 Integration

ArcSite Provides Out-of-the-Box Standard Integration for essential features. With Standard Integration, it supports auto-pushing Drawing PDFs, creating Sales data in I360 Appointments. No extra custom development is needed.

Standard Integration for I360

Integrating I360 into ArcSite

For detailed settings and connection methods, please consult the setup guide: I360 Integration Setup Part One - Customer Steps.

Associating I360 Appointments with ArcSite Projects

Validating the Integration

Once you've successfully created the project and associated with the appointment, you can verify the integration status in ArcSite follow these steps:

  1. Check if the project created via the API appears in the project List. If it's missing, this indicates a project creation failure. Untitled
  2. Within the ArcSite app, create a drawing within the project and upload it to the Cloud.
  3. On the ArcSite user site, select the uploaded drawing.
  4. In the Takeoff & Estimate Tab, ensure the Send to I360 button is visible. Untitled
  5. If the Send to I360 button appears, it confirms the successful association, allowing the project to push data to associated i360 appointment. If the button is missing, this indicates a project association failure. Please check the associate API for more information.

Connecting Products between ArcSite and I360

ArcSite supports the connection of one I360 product to an ArcSite product through the ArcSite Product Manager web page in user site. Once connected, this connection relationship will be used when ArcSite pushes Line Items data to I360.

To connect products, follow these steps:

  1. Verify that the I360 environment is correctly set up, and the product exists in both I360 and ArcSite. Untitled
  2. Navigate to Integrations -> Product Manager to locate the product you wish to connect. Untitled
  3. Click the connect button and select the corresponding I360 product. Untitled
  4. After connecting, the product status changes to connected, and the Connect button becomes Update. Untitled
  5. If you wish to disconnect products, you can click Update, followed by the Disconnect button. Untitled

Data Pushing Details

We categorize data pushing into three types based on the data involved:

Automatic Push for Drawing PDF and Proposal PDFs

Manual Push for Proposal PDF

Manual Push for Line Items and Pricing

APIs for I360

Associate I360 Appointment with ArcSite Project

curl -X POST 'https://api.arcsite.com/v1/i360/associate_project' \
-H 'Authorization: Bearer **your_api_token_here**' \
-H 'Content-Type: application/json' \
-d '{
  "appointment_id": "AXh09668400GJgk",
  "project_id": "36029621653386360"
}'

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"
  },
  "tags": [
    "tag1",
    "tag2"
  ]
}

This endpoint establishes an association between an I360 appointment and an existing ArcSite project.

HTTP Request

POST https://api.arcsite.com/v1/i360/associate_project

Parameters

Parameter Type Description
appointment_id String (required) The ID of the appointment in I360.
project_id String (required) The ID of the existing ArcSite project.

Batch associate I360 Appointment with ArcSite Project

curl -X POST 'https://api.arcsite.com/v1/i360/batch/associate_project' \
-H 'Authorization: Bearer **your_api_token_here**' \
-H 'Content-Type: application/json' \
-d '{
  "items": [
    {
      "appointment_id": "AXh09668400GJgk",
      "project_id": "36029621653386360"
    },
    {
      "appointment_id": "BXh09668400GJgk",
      "project_id": "36029621653386361"
    },
    {
      "appointment_id": "CXh09668400GJgk",
      "project_id": "36029621653386362"
    }
  ]
}'

The above command returns JSON structured like this:

{
"success_items": [
  "appointment_id": "AXh09668400GJgk",
  "project_id": "36029621653386360"

],
"fail_items": [
  "appointment_id": "BXh09668400GJgk",
  "project_id": "36029621653386361",
  "message": "The project is already associated with an i360 Appointment"
]
}

This endpoint establishes multiple associations between I360 appointments and existing ArcSite projects.

HTTP Request

POST https://api.arcsite.com/v1/i360/batch/associate_project

Parameters

Parameter Type Description
items list[AssociateItem] array of associate items

AssociateItem

Parameter Type Description
appointment_id String (required) The ID of the appointment in I360.
project_id String (required) The ID of the existing ArcSite project.

Connected I360 Product

In ArcSite, after setting up the I360 environment, you can connect an I360 Product to an ArcSite product within the ArcSite website.

To retrieve the connected I360 Product ID using an ArcSite product ID, you can utilize this API:

curl 'https://api.arcsite.com/v1/i360/connected_product/<arcsite_product_id>' \
-H 'Authorization: Bearer **your_api_token_here**'

The above command returns JSON structured like this:

{
  "connected_product_id": "AXh09668400GJgk"
}

This endpoint provides the connected I360 product ID.

HTTP Request

POST https://api.arcsite.com/v1/i360/connected_product/<arcsite_product_id>

Webhooks for I360

Prompt after exporting proposal in App

This webhook is triggered after exporting a Proposal PDF in the ArcSite App and the user chooses “Yes” or “No” when prompted.

This webhook will only be triggered if:

Prompt after exporting proposal in App Webhook Payload

Parameter Type Description
project_id String (required) The project id of the project
drawing_id String (required) The drawing of the project
appointment_id String (required) Associated Appointment ID
yes_no Boolean (required) User Selection

Zoho CRM Integration

ArcSite Provides Out-of-the-Box Basic Standard Integration for essential features. With Basic Standard Integration, it supports associating Zoho CRM Record with ArcSite project, and pushing proposal PDF from ArcSite to associated record as attachment in Zoho CRM. No extra custom development is needed.

We also provide Webhooks for customization. Please check out those Webhooks and Customization for more details.

Zoho CRM Basic Standard Integration

Integrating Zoho CRM into ArcSite

For detailed settings and connection methods, please consult the setup guide: Connecting Zoho CRM in ArcSite.

Associating Zoho CRM Records with ArcSite Projects

Validating the Integration

Once you've successfully created the project and associated with the Zoho CRM record, you can verify the integration status in ArcSite follow these steps:

  1. Check if the Project created via the API appears in the Project List. If it's missing, this indicates a project creation failure. Untitled
  2. Within the ArcSite app, create a Drawing within the Project and upload it to the Cloud.
  3. On the ArcSite user site, select the uploaded Drawing.
  4. In the Takeoff & Estimate Tab, ensure the Send to Zoho CRM button is visible. Untitled
  5. If the Send to Zoho CRM button appears, it confirms the successful association, allowing the Project to push proposal PDF as attachment to associated Zoho CRM record. If the button is missing, this indicates a project association failure. Please check the associate API for more information.

Data Pushing Details

Push Proposal PDF file

Webhooks and Customization for Zoho CRM

You can add webhooks to do some customized logic. Check out Webhooks for Zoho CRM.

A Customization Example:

Let’s say you want to create a Quotes record with product line items in Zoho CRM, when you push Proposal PDF attachment.

Implementation Steps:

  payload = get_payload_from_webhook()
  # extract drawing_id, zoho_module_name and zoho_record_id from payload
  drawing_id = payload.drawing_id
  zoho_module_name = payload.zoho_module_name
  zoho_record_id = payload.zoho_record_id
  if payload.yes_no is False
     # Do nothing or other logic
  else
     # Fetch all Line Items info using drawing_id
     ine_items = request_arcsite_drawing_line_items_api(drawing_id)
     # Create Zoho CRM Quotes or other record with the line items data
  1. Complete Basic Integration and add the Proposal Exported in App Webhook.
  2. ArcSite sends payload data to your webhook URL. You should to extract the yes_no from the payload and handle the logic like the sample code right side.
  3. Extract Drawing ID and zoho_module and zoho_record_id from the payload.
  4. Fetch all Line items info using the drawing_id via Drawing Line Items API.
  5. Create Quotes record with Drawing Line Items Data

    • Deal_Name: Use the zoho_module and zoho_record_id to fetch the Deals record name from Zoho CRM.
    • Discount: Use the sum of discount and markup from the drawing line items data.
    • Tax: Use line items sum oftax as the Tax of Quotes record.
    • Quoted_Items: Use the line items data to create the Quoted_Items of Quotes record
      • Product_Name: Use the name of the line item, you can use the name to fetch the product from Zoho CRM.
      • Quantity: Use the quantity of line item
      • Price_Book_Name: Use the zoho_product_id fetched before to get or create PriceBook data from Zoho CRM.
  6. Optionally, modify the record status or add other custom features.

APIs for Zoho CRM

Associate Zoho CRM Record with ArcSite Project

curl -X POST 'https://api.arcsite.com/v1/zoho_crm/associate_project' \
-H 'Authorization: Bearer **your_api_token_here**' \
-H 'Content-Type: application/json' \
-d '{
  "zoho_module": "Deals",
  "zoho_record_id": "598254512451545",
  "project_id": "36029621653386360"
}'

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"
  },
  "tags": [
    "tag1",
    "tag2"
  ]
}

This endpoint establishes an association between a Zoho CRM record and an existing ArcSite project.

HTTP Request

POST https://api.arcsite.com/v1/zoho_crm/associate_project

Parameters

Parameter Type Description
zoho_module String (required) The Name of the Record in Zoho CRM, the value should one of Deals, Quotes, Leads and Contacts.
zoho_record_id String (required) The ID of the record in Zoho CRM.
project_id Int (required) The ID of the existing ArcSite project.

Webhooks for Zoho CRM

Prompt after exporting proposal in App for Zoho CRM

This webhook is triggered after exporting a Proposal PDF in the ArcSite App and the user chooses “Yes” or “No” when prompted.

This webhook will only be triggered if::

Prompt after exporting proposal in App Webhook Payload

Parameter Type Description
project_id String (required) The project id of the project
drawing_id String (required) The drawing of the project
zoho_module String (required) The name of the Zoho CRM module, the value should one of Deals, Quotes, Leads and Contacts.
zoho_record_id Boolean (required) The record ID in Zoho CRM
yes_no Boolean (required) User Selection

Salesforce Integration

ArcSite Provides Out-of-the-Box Basic Standard Integration for essential features. With Basic Standard Integration, it supports auto-pushing drawing PDFs, proposal PDFs and pricing data to Salesforce.

We also provide Webhooks and APIs for customization. Please check out those Webhooks and APIs for customization for more details.

Basic Standard Integration for Salesforce

Integrating Salesforce into ArcSite

For detailed settings and connection methods, please consult the setup guide: ArcSite Salesforce Standard Integration.

Associating Salesforce Opportunity with ArcSite Projects

Validating the Integration

Once you've successfully created the project and associated with the opportunity, you can verify the integration status in ArcSite follow these steps:

  1. Check if the project created via the API appears in the project List. If it's missing, this indicates a project creation failure. Untitled
  2. Within the ArcSite app, create a drawing within the project and upload it to the Cloud.
  3. On the ArcSite user site, select the uploaded drawing.
  4. In the Takeoff & Estimate Tab, ensure the Send to Salesforce button is visible. Untitled
  5. If the Send to Salesforce button appears, it confirms the successful association, allowing the project to push data to associated salesforce opportunity. If the button is missing, this indicates a project association failure. Please check the associate API for more information.

Connecting Products between ArcSite and Salesforce

ArcSite supports the connection of one salesforce product2 to an ArcSite product through the ArcSite Product Manager web page in user site. Once connected, this connection relationship will be used when ArcSite pushes Line Items data to Salesforce.

To connect products, follow these steps:

  1. Verify that the Salesforce environment is correctly set up, and the product exists in both Salesforce and ArcSite. Untitled
  2. Navigate to Integrations -> Product Manager to locate the product you wish to connect. Untitled
  3. Click the connect button and select the corresponding Salesforce Product2. Untitled
  4. After connecting, the product status changes to connected, and the Connect button becomes Update. Untitled
  5. If you wish to disconnect products, you can click Update, followed by the Disconnect button. Untitled

Data Pushing Details

We categorize data pushing into three types based on the data involved:

Automatic Push for Drawing PDF

Manual Push for Proposal PDF

Manual Push for Line Items and Pricing

Webhooks and APIs for Salesforce Customization

If you need more customized features, ArcSite's Extended Integration offers specialized Webhooks and APIs for Salesforce.

Customization Examples:

Create a Quote when you don't sell the project

Let's say you've edited a Drawing and want to auto-generate Salesforce Quote when you select "No" in "Do you want to push this proposal to Salesforce?" pop-up.

Implementation Steps:

 payload = get_payload_from_webhook()
 if payload.yes_no is False
     # extract drawing_id and salesforce object data from payload
     drawing_id = payload.drawing_id
     salesforce_object_type = payload.salesforce_object_type
     salesforce_object_id = payload.salesforce_object_id
     # Fetch all Line Items info using drawing_id
     line_items = request_arcsite_drawing_line_items_api(drawing_id)
     # Generate Salesforce Quote
     # Create Salesforce QuoteLineItems
 else
     # Do nothing, arcsite will push line items data.
  1. Complete Basic Integration and subscribe to the Proposal Exported in App Webhook.
  2. ArcSite sends payload data to your webhook URL. You should to extract the yes_no from the payload and handle the logic like the sample code right side.
  3. Extract drawing_id and salesforce_object_type and salesforce_object_id from the payload.
  4. Fetch all Line items info using the drawng_id via Drawing Line Items API.
  5. Generate an Salesforce Quote Object

6.Create Salesforce QuoteLineItems

APIs for Salesforce

Associate Salesforce Opportunity with ArcSite Project

curl -X POST 'https://api.arcsite.com/v1/salesforce/associate_project' \
-H 'Authorization: Bearer **your_api_token_here**' \
-H 'Content-Type: application/json' \
-d '{
  "salesforce_object_type": "Opportunity",
  "salesforce_object_id": "0062v00001J8Z3aAAF",
  "project_id": "36029621653386360"
}'

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"
  },
  "tags": [
    "tag1",
    "tag2"
  ]
}

This endpoint establishes an association between a Salesforce object and an existing ArcSite project.

HTTP Request

POST https://api.arcsite.com/v1/salesforce/associate_project

Parameters

Parameter Type Description
salesforce_object_type String (required) The type of the Object in Salesforce, the value should one of Opportunity and Quote.
salesforce_object_id String (required) The ID of the object in Salesforce.
project_id Int (required) The ID of the existing ArcSite project.

Connected Salesforce Product

In ArcSite, after setting up the Salesforce environment, you can connect a salesforce Product2 to an ArcSite product within the ArcSite website.

To retrieve the connected Salesforce Product2 ID using an ArcSite product ID, you can utilize this API:

curl 'https://api.arcsite.com/v1/salesforce/connected_product/<arcsite_product_id>' \
-H 'Authorization: Bearer **your_api_token_here**'

The above command returns JSON structured like this:

{
  "connected_product_id": "AXh09668400GJgk"
}

This endpoint provides the connected Salesforce Product2 ID.

HTTP Request

POST https://api.arcsite.com/v1/salesforce/connected_product/<arcsite_product_id>

Webhooks for Salesforce

Prompt after exporting proposal in App for Salesforce

This webhook is triggered after exporting a Proposal PDF in the ArcSite App and the user chooses “Yes” or “No” when prompted.

This webhook will only be triggered if:

Prompt after exporting proposal in App Webhook Payload

Parameter Type Description
project_id String (required) The project id of the project
drawing_id String (required) The drawing of the project
salesforce_object_type String (required) The type of the Object in Salesforce, the value should one of Opportunity and Quote.
salesforce_object_id String (required) The associated salesforce object id
yes_no Boolean (required) User Selection