Documents

Documents are files you keep on your account, such as signed agreements, invoices or photos a contact sent. Attach one to a contact so your team sees it on the contact's timeline. For audio you want to send, use Media instead.

Routes

Create a document

Creates the document and returns a signed URL. Then PUT the file to that URL. Send JSON, not the file itself.

curl -X POST https://api-v2.dropcowboy.com/document/public/documents \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "signed-agreement.pdf",
    "document_type": "general",
    "contact_id": "487d8607-e415-4d90-a1e1-f9c1a746e0a1",
    "content_type": "application/pdf",
    "file_size": 248331
  }'

{
  "data": {
    "document_id": "454b21ce-a9bb-446e-ab98-8b9e37162ef5",
    "policy": {
      "url": "https://uploads.example.com/454b21ce-a9bb-446e-ab98-8b9e37162ef5/signed-agreement.pdf?X-Amz-Signature=..."
    },
    "uploaded": false
  },
  "meta": { "request_id": "7fd685f7-c31b-402d-9463-104913357155" }
}

Upload the file with Content-Type: application/octet-stream, whatever the file is. The URL is signed for that type and is valid for 2 days.

curl -X PUT "$POLICY_URL" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @signed-agreement.pdf

With a contact_id, the document appears on the contact and the contact.document.attached webhook fires. See Webhooks.

Create a document from a URL

Takes the same fields, plus source_url. We download the file while you wait, so there's nothing to upload afterwards. The file must be 100 MiB or smaller and download within 30 seconds.

curl -X POST https://api-v2.dropcowboy.com/document/public/documents/from-url \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "invoice-1042.pdf",
    "document_type": "general",
    "contact_id": "487d8607-e415-4d90-a1e1-f9c1a746e0a1",
    "source_url": "https://files.example.com/invoices/1042.pdf"
  }'

{
  "data": {
    "document_id": "dcf7e3d2-4aae-4856-b056-576cd92d88e5",
    "policy": {
      "url": "https://uploads.example.com/dcf7e3d2-4aae-4856-b056-576cd92d88e5/invoice-1042.pdf?X-Amz-Signature=..."
    },
    "uploaded": true
  },
  "meta": { "request_id": "fed55c46-1cdd-4e39-9b28-e2f540f17b5d" }
}

uploaded: true means the file is stored. You can ignore policy.

If the download fails, the call returns an error and no document is created, so you can simply try again.

List documents

curl "https://api-v2.dropcowboy.com/document/public/documents?contact_id=487d8607-e415-4d90-a1e1-f9c1a746e0a1&get_total=true" \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"

{
  "data": {
    "documents": [
      {
        "_id": "66f2b1c4e8a9d3f1a2b4c6da",
        "team_id": "cd5cd773-4617-4b28-854d-d3adc74c96d5",
        "document_id": "454b21ce-a9bb-446e-ab98-8b9e37162ef5",
        "document_type": "general",
        "filename": "signed-agreement.pdf",
        "ext": "pdf",
        "content_type": "application/pdf",
        "file_size": 248331,
        "owner_id": "fa933d82-485f-43b0-80ab-860121f06980",
        "created_at": 1759312800000,
        "created_by": "fa933d82-485f-43b0-80ab-860121f06980",
        "modified_at": null,
        "read_at": null,
        "deleted_at": null
      }
    ],
    "total_documents": 1
  },
  "meta": { "request_id": "e41012f4-85b7-4ff5-b359-be30f78d5861" }
}

A contact_id with no documents, or one that isn't on your account, returns an empty documents array. Timestamps are epoch milliseconds.

Get a document

curl https://api-v2.dropcowboy.com/document/public/documents/454b21ce-a9bb-446e-ab98-8b9e37162ef5 \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"

The response is one document, with the same fields as in the list.

Get a download link

Returns a signed link that downloads the file. The link is valid for 2 days. Request a new one each time rather than storing it.

curl https://api-v2.dropcowboy.com/document/public/documents/454b21ce-a9bb-446e-ab98-8b9e37162ef5/url \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"

{
  "data": {
    "url": "https://files.example.com/454b21ce-a9bb-446e-ab98-8b9e37162ef5/signed-agreement.pdf?X-Amz-Signature=..."
  },
  "meta": { "request_id": "6a91f634-b3ef-427b-857e-5d15a9619cf8" }
}

Delete a document

Removes the document from your account. It no longer appears in lists, and asking for its download link returns 404. The response is the document with deleted_at set.

curl -X DELETE https://api-v2.dropcowboy.com/document/public/documents/454b21ce-a9bb-446e-ab98-8b9e37162ef5 \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"

{
  "data": {
    "document_id": "454b21ce-a9bb-446e-ab98-8b9e37162ef5",
    "filename": "signed-agreement.pdf",
    "deleted_at": 1759399200000,
    "deleted_by": "fa933d82-485f-43b0-80ab-860121f06980"
  },
  "meta": { "request_id": "bb5e8c3c-a3f2-4c69-9e51-cb9c1671606b" }
}

The response shows only some of the fields here. An id that isn't on your account, or a document that's already deleted, returns 404.

Errors

For every other error, see Responses, errors and limits.