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_KEYenvironment 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.

