API — Automatically Create Dynamic Videos via API Integration

Sendspark lets you automatically generate AI-personalized videos via our API.

This is helpful when you want to create dynamic videos based on specific actions your leads take, such as...

Filling out a form
Being added to a list
Signing up for your product
Taking a specific action in your app
And more!

Sendspark API Basics

Where to view Your API Credentials

You can access your information in the API Credentials tab in your Sendspark settings.

What are API Keys and Secrets?

An API Key is specific to your Sendspark workspace. It lets you access your workspace from other applications, so you can take actions via automation.
An API Secret is specific to your Sendspark user profile. Every member of your workspace can generate their own API Secrets. These will let each of you take actions as "you" via automation.

How to Generate an API Key

Go to your API Credentials Tab
Select "Create New Key"
You'll see your API Key appear

How to Generate an API Secret

Click on the Key Icon next to your API Key
Click "Generate New Secret Key"
Your API Secret Key will appear for you to copy and use.
Note that you will never able to view this key again. If you need to use an API Secret in the future, you will have to remember this one, or generate a new API Secret Key.

Sendspark API Rate Limits

All API endpoints are limited to 30 requests per minute rate limit, except `../prospects/bulk, which is limited to 1 request per minute.

API Endpoints to Create Dynamics Videos

Alight, let's dive in! You can read on, or jump to the right section:

Create a dynamic video campaign
List dynamic video campaigns
Get dynamic campaign by ID
Get prospect data by email
Add a single prospect to a dynamic video campaign
Add and process multiple prospects to dynamic campaign
API Health status

API Endpoints to Create Dynamics Videos

Create a dynamic video campaign

POST /v1/workspaces/{workspaceId}/dynamics

Payload:

{
  "name": "Name of dynamic campaign"
}

Response:

Code	Description
200	Successful Example Value Model { "response": { "data": [ { "_id": "997f191e810c19729de860fd", "name": "string", "creator": { "_id": "997f191e810c19729de860fd", "name": "string", "lastName": "string", "email": "name@sendspark.com" }, "createdAt": "2023-11-13", "videosAssets": [ { "_id": "997f191e810c19729de860fd", "provider": "sendspark", "url": "http://www.sendspark.com/", "assetUrl": "http://www.sendspark.com/", "duration": 3.5284, "assetId": "997f191e810c19729de860fd" } ], "folder": "997f191e810c19729de860fd", "workspace": "997f191e810c19729de860fd", "videoProperties": { "sharePage": { "title": "string", "message": "string", "buttons": [ { "position": 1, "label": "string", "link": "http://www.sendspark.com/" } ] } }, "combinedVideo": "false", "dynamicBackground": "true", "metadata": { "version": "1" }, "status": "pending" } ], "links": { "next": { "offset": 0, "limit": 0 } }, "pagination": { "offset": 0, "limit": 0, "total": 0 } }, "statusCode": 204 }
400	Bad Request Example Value Model { "statusCode": 400, "code": "S400-AHVE", "error": "Bad Request", "message": "Invalid request payload input" }
404	Not Found Example Value Model { "statusCode": 404, "error": "Not Found", "message": "Resource not found or invalid access" }
503	Service Unavailable Example Value Model { "statusCode": 503, "error": "Service Unavailable", "message": "Service Unavailable" }

List dynamic campaigns

GET /v1/workspaces/{workspaceId}/dynamics

Code	Description
200	Successful Example Value Model { "response": { "links": { "next": { "offset": 11, "limit": 10, "url": "https://api-gw.sendspark.com/v1/workspaces/w1dnne4qcatrajzwyabsctym0kd/dynamics?offset=11&limit=10" } }, "pagination": { "offset": 1, "limit": 10, "total": 122 }, "data": [ { "videoProperties": { "sharePage": { "title": "", "buttons": [] } }, "metadata": { "version": "2" }, "features": { "voiceCloning": { "enable": false, "status": "completed", "startTime": 0.26, "endTime": 1.5, "textGeneration": "hi {{firstname \| there}},", "stability": 0.95, "similarityBoost": 0.2, "errorPayload": null }, "videoSettings": { "animationType": "fade-out-center-to-fade-in-bottom", "animations": [ { "template": "fade-out-center-to-fade-in-bottom", "element": "bubble", "startTime": 0.5, "endTime": 1.5, "_id": "65e35920fa5764750b23d" } ] }, "transcription": { "status": "completed", "reemplaceWords": [ { "word": "watermelon", "replace": "{{firstname \| there}}", "_id": "65e8ec62920af64750b23e" } ], "language": "en" }, "screenshot": { "animations": { "scrolling": false }, "enable": true } }, "summary": { "processed": 5, "completed": 5, "errored": 0, "deleted": 0 }, "_id": "wcefasgigm11e6tsau4x4k3qqigakogf", "name": "New API Gateway Testing!", "folder": "guvw12sno0hjg7gu5re0m88emeffzfjp", "creator": { "_id": "h6h5p5w7bw3pmeasda0diahy0jv5tmq", "name": "Davi", "lastName": "Duarte Pereira", "email": "davi@sendspark.com", "id": "h6h5p5w7bw3pme4zwtp0diahy0jv5tmq" }, "workspace": "w1dnne4qcatrajascasf8tym0kd", "combinedVideo": false, "dynamicBackground": true, "status": "processing", "videosAssets": [ { "_id": "liywjkphyke1kcxbzzvcnd4dq0mu2mb0", "provider": "sendspark", "url": "https://sendspark.com/share/lasznwqqu6r6iiqmqg7e1vbf1iplu4i0", "assetUrl": "https://stream.mux.com/JeGcyg02RLzYl5EFjlIoLccsmTc7k6HOL/medium.mp4", "duration": 18.209333, "assetId": "ufwbawxuhu3ch4e8mwp5jfze1z6z8506" } ], "createdAt": "2024-03-06T22:21:22.371Z", "prospectList": [ { "resourcesStatus": { "audioCloning": { "enable": false, "status": "pending" }, "screenshot": { "enable": true, "status": "completed" }, "campaign": { "enable": true, "status": "completed" }, "video": { "enable": true, "status": "completed" } }, "campaign": "kphtw5sayaj43g12ca0asdsae9trnuembtk", "contactName": "Kevin", "contactEmail": "kevin@mancity.com", "company": "Manchester City", "jobTitle": "Midfielder", "backgroundUrl": "https://www.mancity.com/", "screenshotUrl": "https://cache.screenshotone.com/c764f6197b71d59c13f8a460fe38e1c0d846123e77417b6160174a343023", "audioUrl": null, "status": "completed", "deletedAt": null, "valid": true, "bulkId": "xvhtv8dn2cahegeaxvu1qksgu7oc389", "_id": "yj9b6ruipktf2o5basfasfqfve40xd7l9", "createdAt": "2024-03-06T22:22:53.630Z", "updatedAt": "2024-03-06T22:22:53.630Z", "validationDetails": [], "isNotified": true }, ], ], "statusCode": 200 }
400	Bad Request Example Value Model { "statusCode": 400, "code": "S400-AHVE", "error": "Bad Request", "message": "Invalid request payload input" }
404	Not Found Example Value Model { "statusCode": 404, "error": "Not Found", "message": "Resource not found or invalid access" }

Get dynamic campaign by ID

GET /v1/workspaces/{workspaceId}/dynamics/{dynamicId}

Code	Description
200	Successful Example Value Model { "_id": "33m7w2ybr75cy6fq7453sasdxpuq3ej", "name": "My new DV Campaign", "videoProperties": { "sharePage": { "calendar": {}, "title": "", "buttons": [] } }, "combinedVideo": false, "dynamicBackground": true, "status": "processing", "creator": { "workspaces": { "lastVisited": { "item": "w1dnne4qcsadfsacx9mf8tym0kd", "role": "admin", "firstName": "John", "lastName": "Doe", "jobTitle": "Developer" }, "list": [ { "onboardingSetup": { "mainFocusOption": "other", "winOption": "other", "teamOption": "team", "mainFocusOptionDetail": "Help Sendspark achieve greatness!", "winOptionDetail": "Helping Sendspark progress towards greatness" }, "role": "owner", "item": "ixjkg1owmngc41u5ugy0mejijuequ4ql", "firstName": "John", "lastName": "Doe", "jobTitle": "Software Engineer", "_id": "ofxfvm18c885sh4p733u2basd3ig", "id": "ofxfvm18c885sh4p733u2bf4bu9hg3ig" }, ] }, "stats": { "views": 0, "plays": 0, "responses": 0, "ctas": 0, "thumbsUp": 0 }, "settings": { "thumbnails": { "imageFormat": "animated" }, "suggestions": { "voiceCloning": { "enabled": true } }, "instantIntegrations": [], "siteConnections": [ { "enabled": true, "_id": "6542d4c713562f000d7d4451", "integration": "6542cfe7a99a21bf8027e127", "id": "6542d4c713562f000d7d4451" } ] }, "_id": "h6h5p5w7bw3pme4zwtp0diahy0jv5tmq", "byGoogle": true, "role": "admin", "status": "pending", "initialized": false, "org": "eninqth5blvhqs4mp4gjhzu0inigcxgs", "name": "Davi", "lastName": "Duarte Pereira", "email": "davi@sendspark.com", "jobTitle": "Dev", "isSubscriptionTrial": true, "onboardingCheckList": [ { "completed": true, "_id": "64752af21b1475000e1f5eec", "onboarding": "637519409555c55ef3b412e8", "id": "64752af21b1475000e1f5eec" }, ], "onboardingCompleted": true, "links": [], "phone": null, "crmShortcuts": [ "6580efd71442b78ab6fe4f69", ], "id": "h6h5p5w7bw3pme4zwtp0diahy0jv5tmq" }, "folder": "3k0vtaysmivgbg7fne2m2ytz1i0orpdz", "workspace": "w1dnne4qcatrajzwy4wacx9mf8tym0kd", "videosAssets": [ { "_id": "mb4snq9ng3g7504kzezzrala996a9k1o", "provider": "sendspark", "url": "https://sendspark.com/share/lasznwqqasdsfmqg7e1vbf1iplu4i0", "assetUrl": "https://stream.mux.com/JeGcygdasasLccsmTc7k6HOL/medium.mp4", "duration": 18.209333, "assetId": "ufwbawxuhu3casfmase1z6z8506" } ], "createdAt": "2024-03-07T14:50:08.643Z", "metadata": { "version": "2" }, "features": { "voiceCloning": { "enable": false, "status": "completed", "startTime": 0.26, "endTime": 1.5, "textGeneration": "hi {{firstname \| there}},", "stability": 0.95, "similarityBoost": 0.2, "errorPayload": null }, "videoSettings": { "animationType": "fade-out-center-to-fade-in-bottom", "animations": [ { "template": "fade-out-center-to-fade-in-bottom", "element": "bubble", "startTime": 0.5, "endTime": 1.5, "_id": "65e9d420asdb79aaa896" } ] }, "transcription": { "status": "completed", "reemplaceWords": [ { "word": "watermelon", "replace": "{{firstname \| there}}", "_id": "65e9d420b39717fa79aaa897" } ], "language": "en" }, "screenshot": { "animations": { "scrolling": false }, "enable": true } } }
400	Bad Request Example Value Model { "statusCode": 400, "code": "S400-AHVE", "error": "Bad Request", "message": "Invalid request payload input" }
404	Not Found Example Value Model { "statusCode": 404, "error": "Not Found", "message": "Resource not found or invalid access" }

Get prospect data by email

GET /v1/workspaces/{workspaceId}/dynamics/{dynamicId}/prospects?contactEmail={contact-email@domain.com}

Code	Description
200	Successful Example Value Model { "contactEmail": "Contact Email, Example: john@example.com", "backgroundUrl": "Backgound URL, Example: https://example.com", "status": "Current prospect status, Example: saved, billed, errored, processing, uploaded, completed", "deletedAt": "Deleted Date if prospect was deleted, Example: 2020-01-01T00:00:00.000Z", "valid": "False if prospect has validation errors", "createdAt": "Create date, example: 2020-01-01T00:00:00.000Z", "updatedAt": "Update date, example: 2020-01-01T00:00:00.000Z", "validationDetails": [ { "validationField": "Show field with errors, Example: contactEmail", "validationMessage": "Show error detail related with field with error, example: Invalid email" } ], "contactName": "Contact Name, example: John Doe", "company": "Company Name, example: Sendspark", "jobTitle": "Job Title, example: Software Engineer", "id": "Internal prospect ID, example: 997f191e810c19729de860fd", "shareUrl": "Public URL to share the final video, example: https://sendspark.com/share/997f191e81" }
400	Bad Request Example Value Model { "statusCode": 400, "code": "S400-AHVE", "error": "Bad Request", "message": "Invalid request payload input" }
404	Not Found Example Value Model { "statusCode": 404, "error": "Not Found", "message": "Resource not found or invalid access" }

Add a single prospect to a dynamic campaign.

POST /v1/workspaces/{workspaceId}/dynamics/{dynamicId}/prospect

Payload:

{
  "processAndAuthorizeCharge": false, // must be "true" for this request to work. This confirm that you understand charges associated with generating dynamic videos above your plan limit.
  "prospectDepurationConfig": {
    "forceCreation": false, // if true, we will create a new prospect even if it already exists
    "payloadDepurationStrategy": "keep-first-valid" | "keep-last-valid" // if a prospect already exists, we will keep the first valid one or the last valid one
  },
  "prospect": {
      "contactName": "John Doe",
      "contactEmail": "johndoe@example.com",
      "company": "Example Company",
      "jobTitle": "Example jobTitle",
      "backgroundUrl": "https://example.com",
      "screenshotUrl": "https://sendspark.com",
  }
}

Responses:

Code	Description
200	Successful Example Value Model { "prospectList": [ { "_id": "63f6a4145a5e755e2e8fe19d", "campaign": "okn4ra9qjl3fs2zpuni426jizysbdcp", "contactName": "John Doe", "contactEmail": "johndoe@example.com", "company": "Example Company", "jobTitle": "Example jobTitle", "backgroundUrl": "https://example.com", "screenshotUrl": "https://sendspark.com", "valid": false, "bulkId": "63f6a4145a5e755e2e8fe19d", "status": "saved", "createdAt": "2023-06-02T00:57:45.447Z", "updatedAt": "2023-06-02T00:57:45.447Z", "deletedAt": "2023-11-13", "validationDetails": "string" } ] }
400	Bad Request Example Value Model { "statusCode": 400, "code": "S400-AHVE", "error": "Bad Request", "message": "Invalid request payload input" }
403	Forbidden Example Value Model { "statusCode": 403, "code": "S403-UPLD", "error": "Forbidden", "message": "Invalid request payload input / Any error from provider" }
404	Not Found Example Value Model { "statusCode": 404, "error": "Not Found", "message": "Resource not found or invalid access" }
503	Service Unavailable Example Value Model { "statusCode": 503, "error": "Service Unavailable", "message": "Service Unavailable" }

Add and process multiple prospects to dynamic campaign

POST /v1/workspaces/{workspaceId}/dynamics/{dynamicsId}/prospects/bulk

Payload:

{
  "processAndAuthorizeCharge": false, // must be "true" for this request to work. This confirm that you understand charges associated with generating dynamic videos above your plan limit.
  "prospectDepurationConfig": {
    "forceCreation": false, // if true, we will create a new prospect even if it already exists
    "payloadDepurationStrategy": "keep-first-valid" | "keep-last-valid" // if a prospect already exists, we will keep the first valid one or the last valid one
  },
  "prospectList": [
    {
      "contactName": "John Doe",
      "contactEmail": "johndoe@example.com",
      "company": "Example Company",
      "jobTitle": "Example jobTitle",
      "backgroundUrl": "https://example.com",
      "screenshotUrl": "https://sendspark.com",
    }
  ]
}

Responses:

Code	Description
200	Successful Example Value Model { "name": "My Dynamic Campaign", "videoProperties": { "sharePage": { "title": "Hello there!", "message": "welcome to my dynamic campaign", "buttons": [ { "position": 1, "label": "string", "link": "http://www.sendspark.com/" } ] } }, "metadata": { "version": 1 }, "combinedVideo": false, "dynamicBackground": false, "status": "pending", "creator": "okn4ra9qjlpzhs2zpuni426jizysbdcp", "folder": "ibdls2hjvaebvg0k4mz0zgvndbai9th7", "workspace": "3vwdfm4jmhfyzt1yqp0r8v3qgaocrczb", "videosAssets": [ "string" ], "_id": "63f6a4145a5e755e2e8fe19d", "createdAt": "2021-03-01T00:00:00.000Z", "deletedAt": "2023-11-13", "prospectList": [ { "_id": "63f6a4145a5e755e2e8fe19d", "campaign": "okn4ra9qjl3fs2zpuni426jizysbdcp", "contactName": "John Doe", "contactEmail": "johndoe@example.com", "company": "Example Company", "jobTitle": "Example jobTitle", "backgroundUrl": "https://example.com", "screenshotUrl": "https://sendspark.com", "valid": false, "bulkId": "63f6a4145a5e755e2e8fe19d", "status": "saved", "createdAt": "2023-06-02T00:57:45.447Z", "updatedAt": "2023-06-02T00:57:45.447Z", "deletedAt": "2023-11-13", "validationDetails": "string" } ] }
400	Bad Request Example Value Model { "statusCode": 400, "code": "S400-AHVE", "error": "Bad Request", "message": "Invalid request payload input" }
403	Forbidden Example Value Model { "statusCode": 403, "code": "S403-UPLD", "error": "Forbidden", "message": "Invalid request payload input / Any error from provider" }
404	Not Found Example Value Model { "statusCode": 404, "error": "Not Found", "message": "Resource not found or invalid access" }
503	Service Unavailable Example Value Model { "statusCode": 503, "error": "Service Unavailable", "message": "Service Unavailable" }

API Health status

GET /v1/auth/health

Code	Description
200	Successful Example Value Model { "message": "everything is ok!" }
404	Not Found Example Value Model { "statusCode": 404, "error": "Not Found", "message": "Resource not found or invalid access" }