Skip to main content

​
POST /v1/pdf/edit/replace-text

When using regular expressions in JSON payloads, ensure that backslashes are properly escaped. For example, a single backslash \ should be written as \\.

​
Attributes

Attributes are case-sensitive and should be inside JSON for POST request. for example: { "url": "https://example.com/file1.pdf" }
AttributeTypeRequiredDefaultDescription
urlstringYes-URL to the source file url attribute
httpusernamestringNo-HTTP auth user name if required to access source URL.
httppasswordstringNo-HTTP auth password if required to access source URL.
searchStringsarray[string]Yes-The array of strings to search.
replacementLimitintegerNo0Limit the number of searches & replacements for every item. The value 0 means every found occurrence will be replaced.
caseSensitivebooleanNotrueSet to false to don’t use case-sensitive search.
regexbooleanNofalseSet to true to use regular expression for search string(s).
namestringNo-File name for the generated output, the input must be in string format.
expirationintegerNo60Set the expiration time for the output link in minutes. After this specified duration, any generated output file(s) will be automatically deleted from PDF.co Temporary Files Storage. The maximum duration for link expiration varies based on your current subscription plan. To store permanent input files (e.g. re-usable images, pdf templates, documents) consider using PDF.co Built-In Files Storage.
pagesstringNoall pagesSpecify page indices as comma-separated values or ranges to process (e.g. “0, 1, 2-” or “1, 2, 3-7”). The first-page index is 0. Use ”!” before a number for inverted page numbers (e.g. “!0” for the last page). If not specified, the default configuration processes all pages. The input must be in string format.
passwordstringNo-Password for the PDF file.
asyncbooleanNofalseSet async to true for long processes to run in the background, API will then return a jobId which you can use with the Background Job Check endpoint. Also see Webhooks & Callbacks
replaceStringsarray[string]Yes-The array of replacements strings.
profilesobjectNo-See Profiles for more information.
    AutoCropImagesbooleanNofalseIf you require to crop empty space around an inserted image use the following: profiles": { 'AutoCropImages': true }
    outputDataFormatstringNo-If you require your output as base64 format, set this to base64
    DataEncryptionAlgorithmstringNo-Controls the encryption algorithm used for data encryption. See User-Controlled Encryption for more information. The available algorithms are: AES128, AES192, AES256.
    DataEncryptionKeystringNo-Controls the encryption key used for data encryption. See User-Controlled Encryption for more information.
    DataEncryptionIVstringNo-Controls the encryption IV used for data encryption. See User-Controlled Encryption for more information.
    DataDecryptionAlgorithmstringNo-Controls the decryption algorithm used for data decryption. See User-Controlled Encryption for more information. The available algorithms are: AES128, AES192, AES256.
    DataDecryptionKeystringNo-Controls the decryption key used for data decryption. See User-Controlled Encryption for more information.
    DataDecryptionIVstringNo-Controls the decryption IV used for data decryption. See User-Controlled Encryption for more information.
    YAdjustmentForReplacementTextintegerNo-Adjust the vertical position of the replaced text, ensuring proper alignment with the rest of the document. See Adjust Text Alignment for more details.

​
Adjust Text Alignment

Users may have encountered an issue when using this API endpoint to replace text in a PDF document. The replaced text might appear slightly higher than the original text or the surrounding text, causing alignment issues. To fix this issue, we have added a new parameter called YAdjustmentForReplacementText in the profiles parameter of the API request. This parameter allows you to adjust the vertical position of the replaced text, ensuring proper alignment with the rest of the document. Negative values for this parameter move text up, positive values move text down. Here’s an example of how to use the YAdjustmentForReplacementText parameter. In this example API request, the YAdjustmentForReplacementText parameter has been set to -1, which moves the replaced text 1 unit up vertically, resulting in better alignment with the original text. 
{
 "profiles": "{'YAdjustmentForReplacementText': '-1'}"
}

​
Query parameters

No query parameters accepted.

​
Responses

ParameterTypeDescription
urlstringDirect URL to the final PDF file stored in S3.
outputLinkValidTillstringTimestamp indicating when the output link will expire
pageCountintegerNumber of pages in the PDF document.
errorbooleanIndicates whether an error occurred (false means success)
statusstringStatus code of the request (200, 404, 500, etc.). For more information, see Response Codes.
namestringName of the output file
creditsintegerNumber of credits consumed by the request
remainingCreditsintegerNumber of credits remaining in the account
durationintegerTime taken for the operation in milliseconds

​
Example Payload

To see the request size limits, please refer to the Request Size Limits.
{
  "url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-search-and-replace/sample-agreement-template-signature-page-1.pdf",
  "searchStrings": [
    "[CLIENT-NAME]",
    "[CLIENT-COMPANY]"
  ],
  "replaceStrings": [
    "John Doe",
    "Skynet 3000"
  ],
  "caseSensitive": true,
  "replacementLimit": 1,
  "pages": "",
  "password": "",
  "name": "finalFile",
  "async": false
}

​
Example Response

To see the main response codes, please refer to the Response Codes page.
{
  "url": "https://pdf-temp-files.s3.amazonaws.com/e79f0b9c82984740973ca670d7c93cad/finalFile.pdf",
  "pageCount": 1,
  "error": false,
  "status": 200,
  "name": "finalFile.pdf",
  "remainingCredits": 99089875,
  "credits": 21
}
Inconsistent URL Encoding in cURL Output: When using cURL to make API requests, the output JSON may show URL characters encoded as Unicode escape sequences. For example, the ampersand character (&) may appear as \u0026 in the cURL output. This is normal JSON encoding behavior and does not affect the validity of the URL. The URL will function correctly when used, as JSON parsers automatically decode these escape sequences. If you’re parsing the response programmatically, your JSON parser will handle this conversion automatically.

​
Code Samples

  • CURL
  • JavaScript/Node.js
  • Python
  • Java
  • PHP
curl --location --request POST 'https://api.pdf.co/v1/pdf/edit/replace-text' \
--header 'Content-Type: application/json' \
--header 'x-api-key: *******************' \
--data-raw '{
"url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-to-text/sample.pdf",
"name": "pdfWithTextReplaced",
"caseSensitive": "false",
"searchString": "Your Company Name",
"replaceString": "Acme ltd.",
"replacementLimit": 0,
"async": false
}'