Quickstart

API v1 is being deprecated. Use v2 for new integrations. For existing integrations, see the migration guide and API Reference v1.

Create a project and receive a webhook using API v2. The examples use sandbox.

Before you start:

  • Get a sandbox API key. Create one in Settings → API Keys, or ask your Artemis administrator.
  • Assign it to a user. Choose a user with the permissions your integration needs. See Authentication & API Keys.
  • Store it on your server. Set the ARTEMIS_API_KEY environment variable. Never expose the key in a browser.

This guide uses v2 webhooks. Existing v1 subscriptions remain unchanged when you start calling API v2.

API v2

1. Verify authentication

Your API key must be attributed to a user with the required permissions.

curl "https://sales-sandbox-api.artemis.solar/external/v2/projects?limit=10" \
  -H "x-api-key: $ARTEMIS_API_KEY"

Read projects from data. Continue with cursor=NEXT_CURSOR using the opaque page.nextCursor value until it is null. Preserve the same filters across pages. A 403 with ATTRIBUTED_API_KEY_REQUIRED means the key needs user attribution.

2. Create a project

curl -i -X POST "https://sales-sandbox-api.artemis.solar/external/v2/projects" \
  -H "x-api-key: $ARTEMIS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-1042-create-1" \
  --data '{
    "firstName": "Jordan",
    "lastName": "Rivera",
    "email": "jordan.rivera@example.com",
    "phoneNumber": "+14155550123",
    "address": {
      "street": "123 Main St",
      "city": "Pleasanton",
      "state": "CA",
      "zipcode": "94566",
      "countryCode": "US"
    },
    "assignedSalesRepEmail": "salesrep@example.com",
    "externalProjectId": "CRM-1042",
    "electricBill": 180
  }'

Replace sample values and the sales representative. Use a unique key per intended creation; retry a lost response with the same key and payload. See Idempotency.

On 201, save data.id, Location, and ETag. The project is saved; utility setup and automatic design continue in the background.

3. Follow project and design progress

curl -i "https://sales-sandbox-api.artemis.solar/external/v2/projects/PROJECT_ID" \
  -H "x-api-key: $ARTEMIS_API_KEY"

curl "https://sales-sandbox-api.artemis.solar/external/v2/projects/PROJECT_ID/design" \
  -H "x-api-key: $ARTEMIS_API_KEY"

Use data.id as PROJECT_ID and check design status. For writes, supply the operation’s required headers, including If-Match where specified. See API Reference v2 for fields and permissions.

4. Create a v2 webhook subscription

Choose Contract Version V2 in Installer Settings, or create it through REST:

curl -X POST "https://sales-sandbox-api.artemis.solar/external/v2/webhook-subscriptions" \
  -H "x-api-key: $ARTEMIS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: project-events-subscription-1" \
  --data '{
    "installerId": "f7b7db62-29bf-4e70-bf73-a9221674f12a",
    "callbackUrl": "https://integrations.example.com/webhooks/artemis",
    "eventTypes": ["project-created", "project-updated"],
    "isActive": true
  }'

Replace installerId with your installer's ID and callbackUrl with your public HTTPS endpoint. Store the returned data.signingSecret securely; subscription reads do not return it. Keep this secret separate from your API key.

5. Verify and process a v2 event

Verify X-Artemis-Webhook-Signature using the timestamp header and raw body, then enqueue the event and acknowledge with 2xx. Deduplicate by the payload's id. Fetch resource.href from your configured Artemis API environment using your API key to read the current resource. V2 notifications do not contain a data object. See V2 authentication & signing and the event examples.

Use Test Webhook to verify delivery and signing. Sample resource IDs may not exist; update a real sandbox project to test fetching the resource end to end.

If a request fails

Read the HTTP status and the v2 error code, message, and requestId. Use Error Handling and Rate Limits & Idempotency for recovery instructions.