Skip to main content
All CollectionsMake Dynamic Video CampaignsGenerate Videos via Automation
API — Automatically Create Dynamic Videos via API Integration
API — Automatically Create Dynamic Videos via API Integration

Automatically generate dynamic videos for your prospects and customers through API integration.

Bethany Stachenfeld avatar
Written by Bethany Stachenfeld
Updated over 3 months ago

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

  1. Go to your API Credentials Tab

  2. Select "Create New Key"

  3. You'll see your API Key appear

Sendspark API and Secret Keys

How to Generate an API Secret

  1. Click on the Key Icon next to your API Key

  2. Click "Generate New Secret Key"
    ​

    Generate API Secret Key

  3. Your API Secret Key will appear for you to copy and use.

  4. 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:

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/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": true, // 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"
  }
}

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": true, // 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"
}
Did this answer your question?