Custom Fax Headers

When sending faxes via the POST /faxes endpoint, Enterprise API users can include custom headers using predefined template variables. These variables are part of the optional header_options parameter, which is itself part of the fax_options object.

The custom header feature must be enabled on your CorpID first for this to work over the API. Contact your Account Manager to activate custom headers. If you try to use this feature without activation then the default headers will be used.

The following shows a sample fax send using the POST /faxes endpoint with header_options in use:

{
  "destinations": [ { "fax_number": "16144529565", "to_name": "Bob Smith", "to_company":"Acme Widgets Inc." } ],
  "fax_options": {
    "image_resolution": "FINE",
    "include_cover_page": "true",
    "non_billable_retries": "1",
    "billable_retries": "1",
    "custom_CallerID": "18189785900",
    "custom_CSID": "Testing CSID",
    "header_options": {
      "line_1":["Date: ${DATE_TIME1}", "To: ${TO_NUMBER}", "From: ${FROM_NUMBER}","${CSID}", 
         "${FAX_ID}", "Page: ${CURRENT_PAGE} of ${TOTAL_PAGE}"],
      "line_2":["To: example attn: example2"]
    },
    "cover_page_options": { "from_name": "Mary Adams", "subject": "Information Fax","message": "Sample fax" }
  },
  "client_data": {
    "client_code": "client code",
    "client_id": "client id",
    "client_matter": "client matter",
    "client_name": "client name",
    "client_reference_id": "client reference id",
    "billing_code": "This is a test"
  },
  "documents": [ { "document_type": "TXT", "document_content":"VGhpcyBpcyBhIHRlc3QgZmF4Lg==" } ]
}

The Header_Options Parameter

The following is a sample of the optional header_options parameter.

"header_options": {
  "line_1":["Date: ${DATE_TIME1}", "To: ${TO_NUMBER}", "From: ${FROM_NUMBER}", "${CSID}", 
     "${FAX_ID}", "Page: ${CURRENT_PAGE} of ${TOTAL_PAGE}"],
  "line_2":["To: example attn: example2"]
},

'line_1' and 'line_2' are Array type parameters:

If header_options is missing, the standard/default Consensus-formatted header is used.
When header_options is used, then 'line_1' is required but 'line_2' is optional.
When only one item is passed, it is left justified by default.
If more than one item is passed, it follows the rules (which generally is left | ...| N | ...| right with equivalent padding).
In all cases, an empty string is allowed "", supporting a multitude of visual options. Refer to the Manipulating Spacing section below for details.
Character limits per variable are given in the table below. The maximum length for all variables used is 235 characters.

Allowable Variables

Allowable first line variables include:

Variable Name	Description	Syntax	Example	Max Length
Date	Date and time (in customer's time zone)	See Supported DATE_TIME Format section	12/11/19 09:10:45 AM PT	20 alphanumeric
To number	Destination fax number. We use whatever the client passes in the POST /faxes call destinations > fax number field.	${TO_NUMBER}	18885551234	16 numeric
From number	Caller ID field. We use whatever the client passes in the POST /faxes call fax options > custom CallerID field.	${FROM_NUMBER}	18882226789	15 numeric
CSID	Caller subscriber information. We use whatever the client passes in the POST /faxes call fax options > custom CSID field.	${CSID}	eFax Corporate	20 alphanumeric
FaxID	Fax identifier. We use the system generated FaxID the client gets back in the response from the POST /faxes endpoint.	${FAX_ID}	a45db1d9-7caf-7968-e053-690c950a67a0	32 alpha
Current page/Total pages	The current fax page/total number of pages. We get this value from the fax they submit.	${CURRENT_PAGE} of ${TOTAL_PAGE}	4/10	3 alphanumeric each variable

In the POST /faxes endpoint, users can implement these variables in any combination and order. All six can be used or just one. The order of the variables from left to right in the code is how they will appear in the header.

Allowable second line variables include:

Variable Name	Description	Syntax	Example	Max Length
To and Attention	Open text fields	[“To: text Attn: text”]	To: Consensus Attn: Kevin Coffee	50 alpha each field, 100 total

Rejected Requests

The API rejects any request that includes a variable not included in the above lists. Individual fields that go over their character limit are cropped with no errors thrown. If the total number of characters for all variables goes over 235 then the remaining characters are also cropped.

Custom Header Spacing Examples

The following examples show how the custom header will display with a number of allowable items.

Custom Header with One Item

The first (and only) item (CISD) is left justified.

"header_options": {
  "line_1":["${CSID}"]
},

eFax Corporate

Custom Header with Two Items

The first item (CISD) - left justified.

The second item (Page/Total Pages) is centered.

"header_options": {
  "line_1":["${CSID}", "Page: ${CURRENT_PAGE} of ${TOTAL_PAGE}"]
},

eFax Corporate

PAGE: 5/10

Custom Header with Three Items

The first item (CISD) is left justified.

The second item (date and time) is centered.

The third item (Page/Total Pages) is right justified.

"header_options": {
  "line_1":["${CSID}", "Date: ${DATE_TIME1}", "Page: ${CURRENT_PAGE} of ${TOTAL_PAGE}"]
},

eFax Corporate

2019-09-18 07:31:10 AM EDT

PAGE: 5/10

Custom Header with Four Items

The first item (CSID) is left justified.

The second and third items (date and time and FaxID) are evenly spaced from each other between the first and fourth items.

The fourth item (Page/Total Pages) is right justified

"header_options": {
  "line_1":["${CSID}", "Date: ${DATE_TIME1}", "${FAX_ID}", "Page: ${CURRENT_PAGE} of ${TOTAL_PAGE}"]
},

eFax Corporate

2019-09-18 07:31:10 AM EDT

a45db1d9-7caf-7968-e053-690c950a67a0

PAGE: 5/10

Custom Header with Five Items

The first item (CSID) is left justified.

The second, third, and fourth items (date and time, FaxID, From number) are evenly spaced from each other between the first and fourth items.

5th item (Page/Total Pages) - right justified

"header_options": {
  "line_1":["${CSID}", "Date: ${DATE_TIME1}", "${FAX_ID}", "From: ${FROM_NUMBER}", "Page: ${CURRENT_PAGE} of ${TOTAL_PAGE}"]
},

eFax Corporate

2019-09-18 07:31:10 AM EDT

a45db1d9-7caf-7968-e053-690c950a67a0

13238609200

PAGE: 5/10

Custom Header with Six Items

The first item (CSID) is left justified.

The second, third, fourth, and fifth items (date and time, To number, FaxID, From number) are evenly space from each other between the first and sixth items.

The sixth item (Page/Total Pages) is right justified.

"header_options": {
  "line_1":["${CSID}", "Date: ${DATE_TIME1}", "To: ${TO_NUMBER}", "${FAX_ID}", "From: ${FROM_NUMBER}", "Page: ${CURRENT_PAGE} of ${TOTAL_PAGE}"]
},

eFax Corporate

2019-09-18 07:31:10 AM EDT

18883595559

a45db1d9-7caf-7968-e053-690c950a67a0

13238609200

PAGE: 5/10

Manipulating Spacing

If desired, spacing and justification can be manipulated using quotation marks around the variable.

Center Text

To center text, you can manipulate rules by passing:

"header_options":  {
  "line_1":["","${CSID}",""]
},

eFax Corporate

Right Justify Text

To right justify text, you can manipulate rules by passing:

"header_options":  {
  "line_1":["","${CSID}"]
},

eFax Corporate

Blank Header

To pass blank headers, you can manipulate rules by passing by passing:

"header_options":  {
  "line_1":[""]
},

Supported DATE_TIME Formats

For the Date variable, there are seven possible formats. These are:

${DATE_TIME1} - use timecode 1. If no integer is provided (${DATE_TIME}) then this format is used.
${DATE_TIME2} - use timecode 2
${DATE_TIME3} - use timecode 3
${DATE_TIME4} - use timecode 4
${DATE_TIME5} - use timecode 5
${DATE_TIME6} - use timecode 6
${DATE_TIME7} - use timecode 7

The following table lists each of the date/time formats for the available non-default Date variables.

Time code	Description	JAVA
1	ISO 24 hour	yyyy-MM-dd HH:mm:ss
2	US 12 hour	M/d/yyyy K:mm:ss a
3	US 24 hour	M/d/yyyy HH:mm:ss
4	GB 24 hour	dd/MM/yyyy HH:mm:ss
5	JP 24 hour	yyyy/MM/dd H:mm:ss
6	GB 12 hour	dd/MM/yyyy K:mm:ss a
7	JP 12 hour	yyyy/MM/dd K:mm:ss a

Return to the top of this page.